Side navigation API

Import

import { SideNav, SideNavList, SideNavListItem, SideNavListSection } from '@cimpress-ui/react';

Active item

Use the isActive prop on SideNavListItem to indicate the current page.

Preview

Menu item 1Menu item 2Menu item 3

Code

import { RouterProvider, SideNav, SideNavList, SideNavListItem } from '@cimpress-ui/react';
import { IconPlaceholder } from '@cimpress-ui/react/icons';
import { useState } from 'react';

export default function Demo() {
  const [path, setPath] = useState('#1');

  return (
    <RouterProvider navigate={setPath}>
      <SideNav>
        <SideNavList>
          <SideNavListItem href="#1" isActive={path === '#1'} icon={<IconPlaceholder />}>
            Menu item 1
          </SideNavListItem>
          <SideNavListItem href="#2" isActive={path === '#2'} icon={<IconPlaceholder />}>
            Menu item 2
          </SideNavListItem>
          <SideNavListItem href="#3" isActive={path === '#3'} icon={<IconPlaceholder />}>
            Menu item 3
          </SideNavListItem>
        </SideNavList>
      </SideNav>
    </RouterProvider>
  );
}

Copy code Open in StackBlitz

Controlled/uncontrolled collapsible mode (unstable)

When using the unstable collapsible mode, collapse state is configured through UNSTABLE_isCollapsible. Inside app shell, uncontrolled usage is recommended so app shell can manage the state for you.

Use defaultCollapsed to seed the initial collapse state on large viewports:

<SideNav UNSTABLE_isCollapsible={{ defaultCollapsed: true }}>{/* ... */}</SideNav>

defaultCollapsed is only applied on the initial mount. Omit it when you want the side nav to start expanded.

To persist the user’s collapse preference, pair defaultCollapsed with onCollapseChange — for example, by saving the preference to localStorage:

<SideNav
  UNSTABLE_isCollapsible={{
    defaultCollapsed,
    onCollapseChange: (isCollapsed) => {
      localStorage.setItem(STORAGE_KEY, String(isCollapsed));
    },
  }}
>
  {/* ... */}
</SideNav>

Note

In server-side rendering (SSR) scenarios, you should persist user preferences using cookies or a database instead of local storage to prevent hydration errors.

Use controlled collapse state when you need to manage it yourself, for example outside of app shell. Pass isCollapsed together with onCollapseChange:

const [isCollapsed, setIsCollapsed] = useState(false);

<SideNav
  UNSTABLE_isCollapsible={{
    isCollapsed,
    onCollapseChange: setIsCollapsed,
  }}
>
  {/* ... */}
</SideNav>;

Accessibility notes

Side nav renders a navigation landmark.

API reference

SideNav

Displays persistent side navigation for applications with multiple sections or pages.

See side nav usage guidelines.

SideNavProps

children *

ReactNode

The contents of the side navigation. Typically a <SideNavList>.

UNSTABLE_isCollapsible

boolean | ({ defaultCollapsed?: true; isCollapsed?: boolean; onCollapseChange?: (isCollapsed: boolean) => void })

Determines if the side navigation can be collapsed down to an icon-only rail, allowing for more screen space when needed.

Setting to true will enable collapsibility. Passing an object allows for more advanced configuration, including fully controlled usage outside app shell context.

SideNavList

Renders a list of navigation items within SideNav.

SideNavListProps

children *

ReactNode

Navigation items and sections belonging to the list.

SideNavListItem

Renders a single navigation item within SideNavList.

SideNavListItemProps

children *

StringLikeChildren

The text to display as the navigation item label.

href *

string

A URL to link to.

isActive

boolean

Whether the navigation item represents the current page.

icon

ReactNode

An icon displayed before the navigation item label. Required when the side nav is collapsible.

SideNavListSection

Renders a section of navigation items within SideNavList.

SideNavListSectionProps

children *

ReactNode

Navigation items belonging to the section.

label

string

The content to display as the section title.