XDS — Design System

SideNav@xds/core v0.0.13 · XDSSideNav

Usage

A sidebar navigation component for organizing application pages with sections, nested items, and icons. Use SideNav as the primary navigation when an app has 5 or more destinations or requires hierarchical grouping.

ts
import {XDSSideNav} from '@xds/core/SideNav'

Best practices

Guidance	Practices
Do	Use sections to group related navigation items and help users scan for their destination.
Do	Pair outline and filled icon variants so the selected state is visually distinct.
Don't	Include a SideNavHeading when a TopNav is already providing app identity — this duplicates branding.
Don't	Use for filtering content — use tabs or filter buttons instead.

Sub-components

SideNav is a compound component with 5 sub-components.

XDSSideNav

Container with five zones: header, topContent, children (scrollable), footer, and footerIcons. Supports collapsible mode.

Prop	Type	Description
header	ReactNode	Header area (typically XDSSideNavHeading). Sticky.
topContent	ReactNode	Content below the header, e.g., a create button.
children	ReactNode	Navigation sections and items. Scrollable.
footer	ReactNode	Footer area above the icon bar.
footerIcons	ReactNode	Footer icon bar.
collapsible	boolean \| { defaultIsCollapsed?: boolean; isCollapsed?: boolean; onCollapsedChange?: (isCollapsed: boolean) => void; hasButton?: boolean; buttonLabel?: string } (default: false)	Enables collapse behavior. true for uncontrolled with default toggle button, or an object for controlled mode and advanced config (defaultIsCollapsed, isCollapsed + onCollapsedChange, hasButton, buttonLabel).
xstyle	StyleXStyles	StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

XDSSideNavCollapseButton

Toggle button for sidenav collapse. Place inside XDSSideNav (reads context automatically) or outside (pass sideNavRef). Renders as an icon-only ghost button by default.

Prop	Type	Description
sideNavRef	RefObject<HTMLElement \| null>	Ref to the XDSSideNav element. Only needed when the button is rendered outside the sidenav.
label	string	Custom button label. When provided, renders as a text button with chevron. When omitted, renders icon-only.
children	ReactNode	Custom button content. Overrides the default chevron icon and label.

XDSSideNavHeading

Product/suite/account heading with smart interaction boundary logic for links and a menu popover.

Prop	Type	Description
headingrequired	string	Product/app name.
icon	ReactNode	Product/app icon.
headingHref	string	Link for the heading.
superheading	string	Text above the heading.
superheadingHref	string	Link for the superheading.
subheading	string	Text below the heading.
subheadingHref	string	Link for the subheading.
menu	ReactNode	Menu content rendered inside a popover.
headerEndContent	ReactNode	Content rendered at the trailing edge of the heading row, between text and chevron. Useful for badges, status indicators, or compact action buttons. Hidden when collapsed.

XDSSideNavItem

Navigation item with icon, selected state, optional end content, and nesting support via children.

Prop	Type	Description
labelrequired	string	Item label.
as	XDSLinkComponentType	Custom link component.
icon	XDSIconType	Icon displayed in the outline (unselected) variant. See `npx xds docs icons` for valid semantic names.
selectedIcon	XDSIconType	Icon displayed when the item is selected (filled variant). See `npx xds docs icons` for valid semantic names.
isSelected	boolean (default: false)	Marks this item as the current page.
isDisabled	boolean (default: false)	Disabled state.
href	string	Navigation URL.
onClick	(e: MouseEvent) => void	Click handler.
endContent	ReactNode	Right-side content such as badges or counts.
children	ReactNode	Sub-items for nesting.
collapsible	boolean \| { defaultIsCollapsed?: boolean, isCollapsed?: boolean, onCollapsedChange?: (isCollapsed: boolean) => void } (default: false)	Enables collapse behavior for items with children. Pass true for uncontrolled (starts expanded), or an object for controlled mode.

XDSSideNavSection

Section grouping with an optional title, subtitle, and end content.

Prop	Type	Description
titlerequired	string	Section title.
subtitle	string	Section subtitle.
children	ReactNode	Section items.
endContent	ReactNode	Right-side content in the section header.
isHeaderHidden	boolean (default: false)	Visually hides the section header while keeping it accessible to screen readers.
xstyle	StyleXStyles	StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

Examples

Common configurations, variations, and states.

SideNav — End Content

Side navigation items with badges, counts, and context menus as trailing content.

SideNav — Nested Items

Side navigation with collapsible nested items for settings or hierarchical menus.

SideNav — Header with Menu

Side navigation with an account switcher dropdown in the header for multi-account apps.

Usage

import {XDSSideNav} from '@xds/core/SideNav'

Best practices

Guidance	Practices
Do	Use sections to group related navigation items and help users scan for their destination.
Do	Pair outline and filled icon variants so the selected state is visually distinct.
Don't	Include a SideNavHeading when a TopNav is already providing app identity — this duplicates branding.
Don't	Use for filtering content — use tabs or filter buttons instead.

Prop

Type

Description

header

ReactNode

Header area (typically XDSSideNavHeading). Sticky.

topContent

ReactNode

Content below the header, e.g., a create button.

children

ReactNode

Navigation sections and items. Scrollable.

footer

ReactNode

Footer area above the icon bar.

footerIcons

ReactNode

Footer icon bar.

collapsible

boolean | { defaultIsCollapsed?: boolean; isCollapsed?: boolean; onCollapsedChange?: (isCollapsed: boolean) => void; hasButton?: boolean; buttonLabel?: string } (default: false)

Enables collapse behavior. true for uncontrolled with default toggle button, or an object for controlled mode and advanced config (defaultIsCollapsed, isCollapsed + onCollapsedChange, hasButton, buttonLabel).

xstyle

StyleXStyles

StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

Prop

Type

Description

sideNavRef

RefObject<HTMLElement | null>

Ref to the XDSSideNav element. Only needed when the button is rendered outside the sidenav.

label

string

Custom button label. When provided, renders as a text button with chevron. When omitted, renders icon-only.

children

ReactNode

Custom button content. Overrides the default chevron icon and label.

Prop

Type

Description

headingrequired

string

Product/app name.

icon

ReactNode

Product/app icon.

headingHref

string

Link for the heading.

superheading

string

Text above the heading.

superheadingHref

string

Link for the superheading.

subheading

string

Text below the heading.

subheadingHref

string

Link for the subheading.

ReactNode

Menu content rendered inside a popover.

headerEndContent

ReactNode

Content rendered at the trailing edge of the heading row, between text and chevron. Useful for badges, status indicators, or compact action buttons. Hidden when collapsed.

Prop

Type

Description

labelrequired

string

Item label.

XDSLinkComponentType

Custom link component.

icon

XDSIconType

Icon displayed in the outline (unselected) variant. See `npx xds docs icons` for valid semantic names.

selectedIcon

XDSIconType

Icon displayed when the item is selected (filled variant). See `npx xds docs icons` for valid semantic names.

isSelected

boolean (default: false)

Marks this item as the current page.

isDisabled

boolean (default: false)

Disabled state.

href

string

Navigation URL.

onClick

(e: MouseEvent) => void

Click handler.

endContent

ReactNode

Right-side content such as badges or counts.

children

ReactNode

Sub-items for nesting.

collapsible

boolean | { defaultIsCollapsed?: boolean, isCollapsed?: boolean, onCollapsedChange?: (isCollapsed: boolean) => void } (default: false)

Enables collapse behavior for items with children. Pass true for uncontrolled (starts expanded), or an object for controlled mode.

Prop

Type

Description

titlerequired

string

Section title.

subtitle

string

Section subtitle.

children

ReactNode

Section items.

endContent

ReactNode

Right-side content in the section header.

isHeaderHidden

boolean (default: false)

Visually hides the section header while keeping it accessible to screen readers.

xstyle

StyleXStyles

StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.