Playground

Sidebar

A collapsible navigation sidebar with groups, icons and a mobile drawer.

  • Built on native elements
  • 10 parts, named exports
  • A navigation landmark named by the label prop, holding labelled lists of links; the current page has aria-current="page".
  • ArrowUp, ArrowDown, Home and End move focus between items; Tab still moves through them in order.
  • Collapsing keeps every label in the accessibility tree; a tooltip shows it on hover and keyboard focus. The toggle reports aria-expanded.
  • Styles in one file: 02-buttons.css

Import

import '@monoline/css';
import {Sidebar} from '@monoline/react';

Not installed yet? Pick a route.

Copies the source and its styles into your project.

npx monoline add sidebar

Usage

import {type CSSProperties, type ReactNode} from 'react';
import {Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarHeader, SidebarItem, SidebarProvider, SidebarToggle, SidebarTrigger, useSidebar} from '@monoline/react';

const Icon = ({d}: {d: string}) => <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5" aria-hidden="true"><path d={d} /></svg>;

const frame: CSSProperties = {display: 'flex', alignItems: 'stretch', minBlockSize: '22rem', border: '1px solid var(--rule)'};

function Brand() {
  const {collapsed} = useSidebar();
  return <SidebarHeader>{!collapsed && <span>Acme</span>}<SidebarToggle /></SidebarHeader>;
}

function Nav({children}: {children?: ReactNode}) {
  return (
    <>
      <Brand />
      <SidebarContent>
        <SidebarGroup label="Workspace">
          <SidebarItem href="#overview" current icon={<Icon d="M2 8l6-5 6 5v6H2z" />}>Overview</SidebarItem>
          <SidebarItem href="#reports" icon={<Icon d="M3 13V8M8 13V3M13 13V6" />}>Reports</SidebarItem>
          <SidebarItem href="#team" icon={<Icon d="M8 8a3 3 0 100-6 3 3 0 000 6zM2 14c0-3 3-4 6-4s6 1 6 4" />}>Team</SidebarItem>
        </SidebarGroup>
        <SidebarGroup label="Account">
          <SidebarItem href="#billing" icon={<Icon d="M2 4h12v8H2zM2 7h12" />}>Billing</SidebarItem>
        </SidebarGroup>
      </SidebarContent>
      {children}
    </>
  );
}

<SidebarProvider>
  <div style={frame}>
    <Sidebar drawerTitle="Acme"><Nav><SidebarFooter><SidebarGroup><SidebarItem href="#help" icon={<Icon d="M8 14A6 6 0 108 2a6 6 0 000 12zM8 11v.01M6.5 6.5a1.5 1.5 0 113 0c0 1-1.5 1-1.5 2" />}>Help</SidebarItem></SidebarGroup></SidebarFooter></Nav></Sidebar>
    <div style={{padding: 'var(--s5)'}}><SidebarTrigger /></div>
  </div>
</SidebarProvider>

Anatomy

Import the parts you need and nest them like this.

import {Sidebar, SidebarProvider, SidebarHeader, SidebarContent, SidebarGroup, SidebarItem, SidebarFooter, SidebarToggle, SidebarTrigger, useSidebar} from '@monoline/react';

<Sidebar>
  <SidebarProvider />
  <SidebarHeader />
  <SidebarContent />
  <SidebarGroup />
  <SidebarItem />
  <SidebarFooter />
  <SidebarToggle />
  <SidebarTrigger />
  <useSidebar />
</Sidebar>

Examples

Groups and icons

The toggle collapses the sidebar to icons; each label moves into a tooltip. Narrow the window: the sidebar becomes a Menu button and a drawer.

Remember the collapsed state

Control it with `collapsed` and `onCollapsedChange`, here saved with `useLocalStorage`.

Starts collapsed

Props

SidebarProviderProps

PropTypeDefaultDescription
collapsedboolean–Whether the sidebar is collapsed to icons, when controlled. Pair with `onCollapsedChange`.
defaultCollapsedbooleanfalseWhether the sidebar starts collapsed when uncontrolled. Default false.
onCollapsedChange((collapsed: boolean) => void)–Called with the new state when the user collapses or expands the sidebar. Save it here (for example in localStorage) and pass it back as `defaultCollapsed` or `collapsed` to persist the choice.
childrenReactNode'Menu'Your layout: a `Sidebar`, plus any `SidebarToggle` or `SidebarTrigger` anywhere below.

SidebarProps

PropTypeDefaultDescription
labelstring'Toggle sidebar'Names the navigation landmark, in the sidebar and in the drawer. Default "Main".
drawerTitleReactNode'Menu'Names the drawer on small screens (its dialog title). Default "Menu".
renderLinkRenderLink–Renders each `SidebarItem` link, so a client router can handle the click. Default a plain `<a href>`. The returned element must forward its ref and spread extra props (collapsed tooltips need that).
children requiredReactNode'Menu'A `SidebarHeader`, `SidebarContent` and `SidebarFooter`. They render twice: in the sidebar (from 800px) and in the drawer (below 800px).

SidebarGroupProps

PropTypeDefaultDescription
labelReactNode'Toggle sidebar'A heading for the group. Hidden visually (a rule shows instead) when the sidebar is collapsed, still read by screen readers.
children requiredReactNode'Menu'`SidebarItem`s.

SidebarItemProps

PropTypeDefaultDescription
hrefstring–Where the link goes. Not needed with `asChild`.
iconReactNode–An inline SVG with `currentColor`; hidden from screen readers. Shown alone when the sidebar is collapsed.
currentboolean–The current page: sets `aria-current="page"` and the active style.
asChildboolean–Use the child (your router's link) as the anchor. Its text becomes the label.
children requiredReactNode'Menu'The label. Visually hidden when collapsed and shown in a tooltip instead.

SidebarToggleProps

PropTypeDefaultDescription
labelstring'Toggle sidebar'The button's accessible name. It reports expanded or collapsed through `aria-expanded`. Default "Toggle sidebar".

SidebarTriggerProps

PropTypeDefaultDescription
childrenReactNode'Menu'The button text, which is also its name. Default "Menu".

Data Attributes

State is exposed through attributes. Style it with these selectors, not with class toggles.

AttributeStylesheet
[data-side="bottom"]drawer.css
[data-side="end"]drawer.css
[data-side="left"]drawer.css
[data-side="right"]drawer.css
[data-side="start"]drawer.css
[data-side="top"]drawer.css
[aria-current="page"]sidebar.css
[data-collapsed]sidebar.css

CSS classes

ClassStylesheet
.btn02-buttons.css
.btn-block02-buttons.css
.btn-danger02-buttons.css
.btn-ghost02-buttons.css
.btn-lg02-buttons.css
.btn-line02-buttons.css
.btn-sm02-buttons.css
.btn-solid02-buttons.css
.btnicon-button.css
.btn-iconicon-button.css
.btn-smicon-button.css
.tooltiptooltip.css
.commanddialog.css
.dialog-closedialog.css
.dialog-contentdialog.css
.dialog-descriptiondialog.css
.dialog-footerdialog.css
.dialog-headerdialog.css
.dialog-overlaydialog.css
.dialog-titledialog.css
.drawer-contentdialog.css
.drawer-contentdrawer.css
.sidebarsidebar.css
.sidebar-contentsidebar.css
.sidebar-drawersidebar.css
.sidebar-footersidebar.css
.sidebar-groupsidebar.css
.sidebar-group-labelsidebar.css
.sidebar-headersidebar.css
.sidebar-iconsidebar.css
.sidebar-innersidebar.css
.sidebar-itemsidebar.css
.sidebar-labelsidebar.css
.sidebar-listsidebar.css
.sidebar-togglesidebar.css
.sidebar-triggersidebar.css

Customization

Style it with the kit's tokens in your own CSS, loaded after @monoline/css. Prefer the attributes above over extra classes. See Theming for every token.

app.css
.btn {
  border-color: var(--accent);
}
.btn[data-side="bottom"] {
  background: var(--wash);
}

Accessibility

  • A navigation landmark named by the label prop, holding labelled lists of links; the current page has aria-current="page".
  • ArrowUp, ArrowDown, Home and End move focus between items; Tab still moves through them in order.
  • Collapsing keeps every label in the accessibility tree; a tooltip shows it on hover and keyboard focus. The toggle reports aria-expanded.
  • Below 800px the sidebar is hidden and the Menu button opens it in a left drawer: focus is trapped, Escape closes it and focus returns to the button. Choosing a link closes it.
  • In right-to-left layouts the sidebar sits on the right and the drawer opens from the right.

Keyboard

KeysAction
Home / EndMove focus between items
TabStill moves through them in order
EscapeCloses it and focus returns to the button