Sidebar

Sidebars provide persistent app navigation with collapsible, resizable, and mobile-responsive layouts.

Try it

Usage

Wrap the layout in RuiSidebarProvider. Compose header, content, groups, and menu items with the sidebar sub-components.

import {
  RuiSidebarProvider,
  RuiSidebar,
  RuiSidebarHeader,
  RuiSidebarContent,
  RuiSidebarMenu,
  RuiSidebarMenuItem,
  RuiSidebarMenuButton,
  RuiSidebarInset,
  RuiSidebarTrigger,
} from '@ecopages/radiant-ui/sidebar';
 
<RuiSidebarProvider>
  <RuiSidebar collapsible="icon" defaultOpen>
    <RuiSidebarHeader>Acme</RuiSidebarHeader>
    <RuiSidebarContent>
      <RuiSidebarMenu>
        <RuiSidebarMenuItem>
          <RuiSidebarMenuButton href="/dashboard">Dashboard</RuiSidebarMenuButton>
        </RuiSidebarMenuItem>
      </RuiSidebarMenu>
    </RuiSidebarContent>
  </RuiSidebar>
  <RuiSidebarInset>
    <RuiSidebarTrigger />
    <main>Page content</main>
  </RuiSidebarInset>
</RuiSidebarProvider>Copy

Custom markup

import '@ecopages/radiant-ui/sidebar';
 
<rui-sidebar id="app-sidebar" collapsible="icon" label="Navigation">
  <div data-ref="root" class="rui-sidebar">
    <button data-ref="scrim" type="button" hidden></button>
    <div data-ref="pane" class="rui-sidebar__pane">
      <a href="/dashboard" class="rui-sidebar__menu-button" data-ref="menu-button">Dashboard</a>
    </div>
    <div data-ref="handle" role="separator" hidden></div>
  </div>
</rui-sidebar>Copy

rui-sidebar-trigger stamps [data-ref="button"] and syncs aria-expanded / aria-controls against the sidebar. Each trigger also reflects its controlled sidebar's state, mobile mode, and collapse mode on the trigger host. An explicit controls id targets only that rui-sidebar; if it does not resolve, the trigger stays unattached and does not toggle a nearby sidebar. Without controls, a trigger inside a sidebar uses that ancestor. Placement and glyph styles read only the trigger host and its placement attribute, so an attached trigger follows the sidebar's mobileBreakpoint rather than the viewport width, including when providers are nested.

Before a trigger attaches (the server-rendered paint), placement styles treat viewports below 768px as mobile and read the sidebar whose pane holds the trigger, else the only sidebar of its nearest provider (child combinators, so nested providers stay independent). Other triggers, such as inset triggers shared by two sidebars in one provider, stay visible until they attach.

Collapsible modes

icon collapses to icons only. full hides the sidebar entirely. off keeps it always visible.

Active route matching

Enable matchActive with matchMode to highlight the current page in the menu automatically.

Theming

Sidebar surfaces map to semantic surface roles, never Tailwind palette steps:

Rounded corners use rounded-container; the collapsible pane in docs layout sits on surface-container-low. Overrides go at the theme layer, not in component CSS.

Accessibility

• The sidebar renders as a nav landmark with label as its accessible name.
• Collapsed icon-only mode preserves accessible names on menu buttons.
• The trigger button exposes whether the sidebar is expanded or collapsed.

API

RuiSidebar (<rui-sidebar>) coordinates the pane, resize, collapse, and active-route matching. Compose sections with the view helpers; RuiSidebarProvider wires the shell.

Attributes (<rui-sidebar>)

Light-DOM contract (<rui-sidebar>)

Host-owned on <rui-sidebar>: role="complementary", data-state, data-pane-width, …

Methods (<rui-sidebar>)

Light-DOM contract (<rui-sidebar-trigger>)

Attributes (<rui-sidebar-trigger>)

The host writes data-sidebar-state, data-sidebar-mobile, and data-sidebar-collapsible on <rui-sidebar-trigger>. data-sidebar-mobile and data-sidebar-collapsible appear once the trigger attaches to its sidebar. Until then, data-sidebar-state matches the server render: collapsed for inset, expanded otherwise.

Events

View helpers

CSS classes

Public BEM classes (documented via @cssclass):

Theme roles