Sidebar Navigation controls both flat and hierarchical navigation structures within an application's sidebar. The navigation components are presentational and can be used to create navigation structures ranging from simple lists to complex, deeply nested structures.
We recommend limiting the nesting depth to 3 levels. For navigation beyond this depth, consider also using the In-page Navigation.
Nested sidebar navigation uses the ARIA Disclosure pattern.
- You must provide an
aria-labelprop for screen reader software.aria-label="Main"is read as "Main Navigation", with the word "navigation" being pulled from the navigation element. - Additional controls or actions should be placed as siblings to each
SidebarNavigationItemin the navigation, not nested within. - Every
SidebarNavigationItemmust implement an anchor element by assigning a valid URL to thehrefattribute. - A
selectedSidebarNavigationItemis designated as the "current page" viaaria-current="page".
In its most basic form, Sidebar Navigation can be used to create a flat list of navigation items. This is ideal for smaller applications or single-product use cases.
Each SidebarNavigationItem should be provided with an href, a valid URL that the user will navigate to upon interaction. This facilitates opening links in new tabs via CMD/CTRL + clicking or right-clicking on the item, ensuring proper keyboard navigation for keyboard-only users.
The SidebarNavigationItem can be decorated with an icon by setting the icon property value to any valid Paste Icon.
To indicate the current page, the selected property should be set on the item that represents the user's current location in the application.
Sidebar Navigation also supports hierarchical information architectures with nested navigation items. You can establish "groups" of navigation sections by using SidebarNavigationSeparator between groups of items.
Each SidebarNavigationDisclosure pairs a heading with its content. SidebarNavigationDisclosureHeading accepts a string as content, which describes the navigation items beneath it in the hierarchy. It should not contain clickable actions. For additional actions associated with a parent navigation item, refer to the Navigation item actions section below.
The icon and selected properties from SidebarNavigationItem can be used on the SidebarNavigationDisclosureHeading to display an icon and indicate the user's current section. When implementing multiple levels of navigation, ensure each selected parent item is displayed down the navigation tree. For instance, in the example below, I can see that I am currently on the "Send a Whatsapp message" item, which is a child page of "Try it out" and "Messaging".
SidebarNavigationItems are listed in the SidebarNavigationDisclosureContent and are displayed when the disclosure is expanded using the SidebarNavigationDisclosureHeading.
When creating a hierarchical navigation structure, ensure the SidebarNavigation component's hierarchical property is set, as it provides additional context for children placed within.
There may be situations where a combination of simple flat structures and nested pages is necessary. The components provided by Sidebar Navigation allow for easy, flexible composition to suit your navigation needs. Pair SidebarNavigationItems with SidebarNavigationDisclosures to create this form of navigation structure.
When mixing, you must ensure hierarchical is set on SidebarNavigation to achieve correct indentation.
When using a flat navigation list and a compact Sidebar variant, only the icons remain visible when the Sidebar collapses. In this situation, ensure the navigation item icons have a title and are not decorative to maintain accessible names for collapsed navigation items.
<Sidebar
sidebarNavigationSkipLinkID={sidebarNavigationSkipLinkID}
topbarSkipLinkID={topbarSkipLinkID}
mainContentSkipLinkID={mainContentSkipLinkID}
collapsed={false}
variant="compact"
>
<SidebarHeader>
<SidebarHeaderIconButton as="a" href="#">
<ProductFlexIcon size="sizeIcon20" decorative={false} title="Go to Flex homepage" />
</SidebarHeaderIconButton>
<SidebarHeaderLabel>Twilio Flex</SidebarHeaderLabel>
</SidebarHeader>
<SidebarBody>
<SidebarNavigation aria-label="main navigation">
<SidebarNavigationItem
href=""
selected
icon={<ProductContactCenterAdminIcon decorative={false} title="Admin" />}
>
Admin
</SidebarNavigationItem>
<SidebarNavigationItem
href=""
icon={<ProductContactCenterTasksIcon decorative={false} title="Agent dashboard" />}
>
Agent dashboard
</SidebarNavigationItem>
<SidebarNavigationItem
href=""
icon={<ProductContactCenterTeamsIcon decorative={false} title="Teams view" />}
>
Teams view
</SidebarNavigationItem>
<SidebarNavigationItem
href=""
icon={<ProductContactCenterQueuesIcon decorative={false} title="Queue stats" />}
>
Queue stats
</SidebarNavigationItem>
<SidebarNavigationItem
href=""
icon={<ProductPrivacyIcon decorative={false} title="Privacy" />}
>
Privacy
</SidebarNavigationItem>
<SidebarNavigationItem
href=""
icon={<ProductUsageIcon decorative={false} title="Insights" />}
>
Insights
</SidebarNavigationItem>
</SidebarNavigation>
</SidebarBody>
</Sidebar>If you are using a collapsible, compact sidebar and decide to hide the navigation items completely when collapsed, remember to set hideItemsOnCollapse on SidebarNavigation.
Regardless of the situation, Sidebar Navigation Disclosures will always be hidden in a collapsed Sidebar.
<Sidebar
sidebarNavigationSkipLinkID={sidebarNavigationSkipLinkID}
topbarSkipLinkID={topbarSkipLinkID}
mainContentSkipLinkID={mainContentSkipLinkID}
collapsed={pushSidebarCollapsed}
variant="compact"
>
<SidebarHeader>
<SidebarHeaderIconButton as="a" href="#">
<ProductSegmentIcon size="sizeIcon20" decorative={false} title="Go to Segment homepage" />
</SidebarHeaderIconButton>
<SidebarHeaderLabel>Twilio Segment</SidebarHeaderLabel>
</SidebarHeader>
<SidebarBody>
<SidebarNavigation aria-label={id} hierarchical hideItemsOnCollapse>
<SidebarNavigationItem href="https://google.com" icon={<ProductHomeIcon decorative />}>
Home
</SidebarNavigationItem>
<SidebarNavigationDisclosure>
<SidebarNavigationDisclosureHeadingWrapper>
<SidebarNavigationDisclosureHeading icon={<ProductConnectionsIcon decorative />} selected>
Connections
</SidebarNavigationDisclosureHeading>
</SidebarNavigationDisclosureHeadingWrapper>
<SidebarNavigationDisclosureContent>
<SidebarNavigationItem href="https://google.com" selected>
Overview
</SidebarNavigationItem>
</SidebarNavigationDisclosureContent>
</SidebarNavigationDisclosure>
<SidebarNavigationDisclosure>
<SidebarNavigationDisclosureHeadingWrapper>
<SidebarNavigationDisclosureHeading icon={<ProductReverseETLIcon decorative />}>
Reverse ETL
</SidebarNavigationDisclosureHeading>
<SidebarBetaBadge as="span">Beta</SidebarBetaBadge>
</SidebarNavigationDisclosureHeadingWrapper>
<SidebarNavigationDisclosureContent>
<SidebarNavigationItem href="https://google.com">Overview</SidebarNavigationItem>
</SidebarNavigationDisclosureContent>
</SidebarNavigationDisclosure>
<SidebarNavigationDisclosure>
<SidebarNavigationDisclosureHeadingWrapper>
<SidebarNavigationDisclosureHeading icon={<ProductPrivacyIcon decorative />}>
Privacy
</SidebarNavigationDisclosureHeading>
</SidebarNavigationDisclosureHeadingWrapper>
<SidebarNavigationDisclosureContent>
<SidebarNavigationItem href="https://google.com">Overview</SidebarNavigationItem>
</SidebarNavigationDisclosureContent>
</SidebarNavigationDisclosure>
<SidebarNavigationDisclosure>
<SidebarNavigationDisclosureHeadingWrapper>
<SidebarNavigationDisclosureHeading icon={<ProductProtocolsIcon decorative />}>
Protocols
</SidebarNavigationDisclosureHeading>
</SidebarNavigationDisclosureHeadingWrapper>
<SidebarNavigationDisclosureContent>
<SidebarNavigationItem href="https://google.com">Overview</SidebarNavigationItem>
</SidebarNavigationDisclosureContent>
</SidebarNavigationDisclosure>
<SidebarNavigationDisclosure>
<SidebarNavigationDisclosureHeadingWrapper>
<SidebarNavigationDisclosureHeading icon={<ProductEngageIcon decorative />}>
Enagage
</SidebarNavigationDisclosureHeading>
</SidebarNavigationDisclosureHeadingWrapper>
<SidebarNavigationDisclosureContent>
<SidebarNavigationItem href="https://google.com">Overview</SidebarNavigationItem>
</SidebarNavigationDisclosureContent>
</SidebarNavigationDisclosure>
<SidebarNavigationDisclosure>
<SidebarNavigationDisclosureHeadingWrapper>
<SidebarNavigationDisclosureHeading icon={<ProductSettingsIcon decorative />}>
Settings
</SidebarNavigationDisclosureHeading>
</SidebarNavigationDisclosureHeadingWrapper>
<SidebarNavigationDisclosureContent>
<SidebarNavigationItem href="https://google.com">Overview</SidebarNavigationItem>
</SidebarNavigationDisclosureContent>
</SidebarNavigationDisclosure>
</SidebarNavigation>
</SidebarBody>
<SidebarFooter>
<SidebarCollapseButton
onClick={() => setPushSidebarCollapsed(!pushSidebarCollapsed)}
i18nCollapseLabel="Close sidebar"
i18nExpandLabel="Open sidebar"
/>
</SidebarFooter>
</Sidebar>There may be instances where a navigation item has some additional information or an action that a user can take, other than navigating to, or showing and hiding child pages. In such cases, these actions should be placed as siblings to the navigation items or disclosure headings. Nesting actionable UI elements can make them undiscoverable for assistive technology users.
Only parent SidebarNavigationDisclosure items can have associated actions. These actions should be placed as siblings to the SidebarNavigationDisclosureHeading, inside the SidebarNavigationDisclosureHeadingWrapper. Alignment will be handled automatically.
State hooks allow you to integrate the disclosure state with your application state and functionality. This can be particularly useful if your application is controlled via a central state management library like Redux, or if actions within the application control how the navigation is displayed beyond the user's interaction with it.
In the simple example below, you can control the expanded state of each disclosure without the user interacting with it.
For more information on using the disclosure state hook, refer to the Disclosure component docs and Disclosure Primitive docs