Skip to content

index.mdx

Latest commit

 

History

History
161 lines (100 loc) · 4.76 KB

index.mdx

File metadata and controls

161 lines (100 loc) · 4.76 KB
title Sidebar
description A collapsible side navigation panel component.
source packages/raystack/components/sidebar

import { preview, positionDemo, variantDemo, accordionGroupDemo, stateDemo, tooltipDemo, collapsibleDemo, hideTooltipDemo, moreDemo } from "./demo.ts";

Anatomy

Import and assemble the component:

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

<Sidebar>
  <Sidebar.Header />
  <Sidebar.Main>
    <Sidebar.Group label="Group name">
      <Sidebar.Item href="#">Item</Sidebar.Item>
      <Sidebar.More label="More">
        <Sidebar.Item href="#">Hidden item</Sidebar.Item>
      </Sidebar.More>
    </Sidebar.Group>
  </Sidebar.Main>
  <Sidebar.Footer />
</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.

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

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).

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.

Examples

Position

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

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

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.

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.

Non-collapsible

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

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.

Accordion Group

Enable accordion on Sidebar.Group to make section items collapsible. You can also pass trailingIcon for section-level actions.

More

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

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