Sidebar

A collapsible side navigation panel component.
1<Flex style={{ width: "100%", height: 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.Item
15        href="#"

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.More label="More">
9        <Sidebar.Item href="#">Hidden item</Sidebar.Item>
10      </Sidebar.More>
11    </Sidebar.Group>
12  </Sidebar.Main>
13  <Sidebar.Footer />
14</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.

More

Renders a sidebar row that opens an Apsara menu with additional Sidebar.Item entries. It can be used inside Sidebar.Group or directly under Sidebar.Main / Sidebar.Footer.

Note: if leadingIcon is not provided, the trigger uses a default dots icon. In collapsed state, it follows the same item tooltip behavior and respects hideCollapsedItemTooltip.

Prop

Type

Examples

Position

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

1<Flex style={{ width: "100%", height: 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.Item
15        href="#"

Variants

Use variant to switch the Sidebar surface style:

  • plain (default): regular surface with side border
  • floating: lifted surface with shadow
  • inset: transparent surface without border or shadow
1<Flex style={{ width: "100%", height: 480 }}>
2  <Sidebar open={true} variant="plain">
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.Item
15        href="#"

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: 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.Item
15        href="#"

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: 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.Item
15        href="#"

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: 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.Item
15        href="#"

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: 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.Item href="#" leadingIcon={<BellIcon width={16} height={16} />}>
15        Overview

More

Use Sidebar.More when you want to keep a section compact and move secondary items into a menu.

1<Flex style={{ width: "100%", height: 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.Item
15        href="#"

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="list" for item containers (Main groups, Footer) and role="listitem" 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