Sidebar

A collapsible side navigation panel component.
1<Flex style={{ width: "100%", height: "100%", minHeight: 480 }}>
2  <Sidebar defaultOpen>
3    <Sidebar.Header>
4      <Flex align="center" gap={3}>
5        <IconButton size={4} aria-label="Logo">
6          <BellIcon width={24} height={24} />
7        </IconButton>
8        <Text size={4} weight="medium" data-collapse-hidden>
9          Apsara
10        </Text>
11      </Flex>
12    </Sidebar.Header>
13    <Sidebar.Main>
14      <Sidebar.Group label="Main">
15        <Sidebar.Item

Anatomy

Import and assemble the component:

1import { Sidebar } from "@raystack/apsara";
2

3<Sidebar>
4  <Sidebar.Header />
5  <Sidebar.Main>
6    <Sidebar.Group label="Group name">
7      <Sidebar.Item href="#">Item</Sidebar.Item>
8    </Sidebar.Group>
9  </Sidebar.Main>
10  <Sidebar.Footer />
11</Sidebar>

API Reference

Root

Groups all parts of the sidebar navigation. Use collapsible={false} to hide the resize handle and prevent toggling. Use hideCollapsedItemTooltip to disable tooltips on items when the sidebar is collapsed.

Prop

Type

Header

The header section is a container component that accepts all div props. It's commonly used to create a header with an icon and title.

Main

The main section wraps navigation groups and items. It accepts all div props and scrolls when content overflows.

Group

Prop

Type

Item

Note: leadingIcon is optional and will show a fallback avatar only in collapsed state. You can pass <></> to render truly nothing. Use the as prop to render as a custom element (e.g. a router Link).

Prop

Type

Footer

The footer section is a container that accepts all div props. It's commonly used for secondary links (e.g. Help, Preferences) and stays at the bottom of the sidebar.

Examples

Position

The Sidebar can be positioned on either the left or right side of the screen.

1<Flex style={{ width: "100%", height: "100%", minHeight: 480 }}>
2  <Sidebar open={true} position="left">
3    <Sidebar.Header>
4      <Flex align="center" gap={3}>
5        <IconButton size={4} aria-label="Logo">
6          <BellIcon width={24} height={24} />
7        </IconButton>
8        <Text size={4} weight="medium" data-collapse-hidden>
9          Apsara
10        </Text>
11      </Flex>
12    </Sidebar.Header>
13    <Sidebar.Main>
14      <Sidebar.Group label="Main">
15        <Sidebar.Item

State

The Sidebar supports expanded and collapsed states with smooth transitions.

The data-collapse-hidden attribute can be used to conditionally hide elements when the sidebar is collapsed.

1<Flex style={{ width: "100%", height: "100%", minHeight: 480 }}>
2  <Sidebar open={true}>
3    <Sidebar.Header>
4      <Flex align="center" gap={3}>
5        <IconButton size={4} aria-label="Logo">
6          <BellIcon width={24} height={24} />
7        </IconButton>
8        <Text size={4} weight="medium" data-collapse-hidden>
9          Apsara
10        </Text>
11      </Flex>
12    </Sidebar.Header>
13    <Sidebar.Main>
14      <Sidebar.Group label="Main">
15        <Sidebar.Item

Custom Tooltip Message

You can customize the tooltip message that appears when hovering over the collapse/expand handle using the tooltipMessage prop.

You can use Sidebar as a controlled component to conditionally render different tooltip messages.

1<Flex style={{ width: "100%", height: "100%", minHeight: 480 }}>
2  <Sidebar defaultOpen tooltipMessage="Toggle navigation">
3    <Sidebar.Header>
4      <Flex align="center" gap={3}>
5        <IconButton size={4} aria-label="Logo">
6          <BellIcon width={24} height={24} />
7        </IconButton>
8        <Text size={4} weight="medium" data-collapse-hidden>
9          Apsara
10        </Text>
11      </Flex>
12    </Sidebar.Header>
13    <Sidebar.Main>
14      <Sidebar.Group label="Main">
15        <Sidebar.Item

Non-collapsible

Set collapsible={false} to hide the resize handle and prevent the sidebar from being collapsed or expanded.

1<Flex style={{ width: "100%", height: "100%", minHeight: 480 }}>
2  <Sidebar defaultOpen collapsible={false}>
3    <Sidebar.Header>
4      <Flex align="center" gap={3}>
5        <IconButton size={4} aria-label="Logo">
6          <BellIcon width={24} height={24} />
7        </IconButton>
8        <Text size={4} weight="medium" data-collapse-hidden>
9          Apsara
10        </Text>
11      </Flex>
12    </Sidebar.Header>
13    <Sidebar.Main>
14      <Sidebar.Group label="Main">
15        <Sidebar.Item

Hide item tooltips when collapsed

Set hideCollapsedItemTooltip to disable tooltips on navigation items when the sidebar is collapsed. Useful when item labels are redundant with the collapse tooltip or you want a cleaner collapsed state.

1<Flex style={{ width: "100%", height: "100%", minHeight: 480 }}>
2  <Sidebar defaultOpen={false} hideCollapsedItemTooltip>
3    <Sidebar.Header>
4      <Flex align="center" gap={3}>
5        <IconButton size={4} aria-label="Logo">
6          <BellIcon width={24} height={24} />
7        </IconButton>
8        <Text size={4} weight="medium" data-collapse-hidden>
9          Apsara
10        </Text>
11      </Flex>
12    </Sidebar.Header>
13    <Sidebar.Main>
14      <Sidebar.Group label="Main">
15        <Sidebar.Item

Accessibility

The Sidebar implements the following accessibility features:

  • Reduced motion — Respects the user's motion preferences. When the system "Reduce motion" setting is enabled, collapse/expand and hover transitions are disabled so the sidebar updates without animation.

  • Proper ARIA roles and attributes

    • role="navigation" for the main sidebar
    • role="banner" for the header
    • role="menuitem" for navigation items
    • aria-expanded to indicate sidebar state
    • aria-current="page" for active items
    • aria-disabled="true" for disabled items

  • Keyboard navigation support

    • Enter/Space to toggle sidebar expansion
    • Tab navigation through interactive elements

  • Screen reader support

    • Meaningful labels for all interactive elements
    • Hidden decorative elements
    • Clear state indicators