Sub nav

import { ... } from '@ag.ds-next/react/sub-nav';

<SubNav
	activePath="#usage"
	links={[
		{ href: '#usage', label: 'Usage' },
		{ href: '#code', label: 'Code' },
		{ href: '#code', label: 'Content' },
		{ href: '#accessibility', label: 'Accessibility' },
	]}
/>

The Sub nav component is a horizontal list of links that can accommodate up to 5 items. It is best suited for navigation to persistent links, or to reveal additional content on the same page. The Sub nav component sometimes accommodates the third level of the information architecture, following the Side nav on a content page. If you need more space for longer lists, consider another form of navigation such as the Side nav, Link list, Inpage nav or Card lists.

The Sub nav component is designed to collapse down to a static vertical list on smaller devices. Progressive disclosure should not be used to enclose the SubNav on small screens.

Do

• use to link to pages within the current section
• keep the user in the same scroll position when navigating between items
• write meaningful labels for each item
• indicate active state for the relevant item

Don’t

• use more than 5 items
• apply more than one SubNav on a page
• use to replicate Tabs behaviour
• use to link to items on the same page – use Inpage nav instead.

Sub nav vs Tabs

The Tabs component and Sub nav are visually similar, but their functionalities differ significantly.

Tabs allow users to switch between different views within a specific section of the same page and should not serve as links that navigate users to new URLs. If you need tab-like navigation, you should use the Sub nav component instead.

Background

The background of the Sub nav must match the background it is being placed on. For example, if Sub nav is placed on a bodyAlt background, set the background prop to bodyAlt.

<Box background="bodyAlt" padding={1}>
	<SubNav
		background="bodyAlt"
		activePath="#usage"
		links={[
			{ href: '#usage', label: 'Usage' },
			{ href: '#code', label: 'Code' },
			{ href: '#code', label: 'Content' },
			{ href: '#accessibility', label: 'Accessibility' },
		]}
	/>
</Box>

Colour

AgDS foreground components respond to the background colour of their parent container. When placed on a dark palette background, the dark palette variant of the component is displayed. When placed on a light palette background the light palette variant is displayed.

This logic ensures sufficient contrast between foreground and background elements is maintained to meet WCAG 2.1 AA, 4:5:1 contrast ratio for text (WCAG 1.4.3) and 3:1 for graphic elements that convey information (WCAG 1.4.11).

This component has a 'bodyAlt' variant. Components with a 'bodyAlt' variant utiliseshadeAlt to highlight interface components and content that sit on 'bodyAlt' background. shadeAlt is also used to fill interactive components, ensuring sufficient contrast is maintained for hover states.

Light palette

<Box background="body" paddingX={{ xs: 0.75, md: 1.5 }} paddingY={1.5}>
	<>
		<Stack gap={1.5} padding={1.5}>
			<H4>Sub nav: on light body background</H4>
			<SubNav
				activePath="#usage"
				links={[
					{ href: '#usage', label: 'Usage' },
					{ href: '#code', label: 'Code' },
					{ href: '#code', label: 'Content' },
					{ href: '#accessibility', label: 'Accessibility' },
				]}
			/>
		</Stack>
		<Stack background="bodyAlt" gap={1.5} padding={1.5}>
			<H4>Sub nav: on light bodyAlt background</H4>
			<SubNav
				activePath="#usage"
				background="bodyAlt"
				links={[
					{ href: '#usage', label: 'Usage' },
					{ href: '#code', label: 'Code' },
					{ href: '#code', label: 'Content' },
					{ href: '#accessibility', label: 'Accessibility' },
				]}
			/>
		</Stack>
	</>
</Box>

Dark palette

<Box background="body" paddingX={{ xs: 0.75, md: 1.5 }} paddingY={1.5} palette="dark">
	<>
		<Stack gap={1.5} padding={1.5}>
			<H4>Sub nav: on dark body background</H4>
			<SubNav
				activePath="#usage"
				links={[
					{ href: '#usage', label: 'Usage' },
					{ href: '#code', label: 'Code' },
					{ href: '#code', label: 'Content' },
					{ href: '#accessibility', label: 'Accessibility' },
				]}
			/>
		</Stack>
		<Stack background="bodyAlt" gap={1.5} padding={1.5}>
			<H4>Sub nav: on dark bodyAlt background</H4>
			<SubNav
				activePath="#usage"
				background="bodyAlt"
				links={[
					{ href: '#usage', label: 'Usage' },
					{ href: '#code', label: 'Code' },
					{ href: '#code', label: 'Content' },
					{ href: '#accessibility', label: 'Accessibility' },
				]}
			/>
		</Stack>
	</>
</Box>

Related components

• Inpage nav – Also known as Page contents, Inpage nav links help users scan page contents and quickly navigate to different sections.
• Link list – Link list is a simple set of vertical or horizontal links used for site navigation and to order information for users.
• Side nav – A vertical list of links used for site navigation, typically placed beside body content.
• Tabs – Tabs are used to categorise content into seperate views. A user can navigate between each section of content, displaying one section at a time.