Sidebar

Overview

Sidebar provides the frame for full-page application shells: persistent navigation, route-driven sidebar layers, a collapsible desktop rail, a mobile sheet, an inset content region, and an optional secondary panel.

Uncontrolled sidebars follow a responsive default: open on wide desktop screens and closed on narrower desktop screens. Users can toggle the sidebar within the current breakpoint; crossing the breakpoint reapplies the responsive default. Pass open to SidebarProvider when a surface needs to control that policy.

Open app shell example

Shell Layout

The /examples shell keeps one SidebarProvider at the route boundary, renders the primary navigation with SidebarLayers, reserves the rounded inset with SidebarInsetFrame and SidebarInset, and renders the matter chat as a secondary SidebarPanel.

import { Outlet, useLocation, useRouter } from "@tanstack/react-router";
import {
  SidebarInset,
  SidebarInsetBarLayer,
  SidebarInsetBarLayers,
  SidebarInsetFrame,
  SidebarLayer,
  SidebarLayers,
  SidebarPanel,
  SidebarProvider,
} from "@tilt-legal/cubitt-components/sidebar";

export function ExamplesShell() {
  const location = useLocation();
  const router = useRouter();
  const isSettingsLayer = location.pathname.startsWith("/examples/settings");
  const hasChatTabs = location.pathname.startsWith("/examples/chat");

  return (
    <SidebarProvider>
      <SidebarLayers rail variant="inset">
        <SidebarLayer id="main">
          <AppSidebar />
        </SidebarLayer>
        <SidebarLayer
          active={isSettingsLayer}
          id="settings"
          onBack={() => router.navigate({ to: "/examples" })}
        >
          <SettingsSidebar />
        </SidebarLayer>
      </SidebarLayers>

      <SidebarInsetFrame>
        <SidebarInsetBarLayers>
          <SidebarInsetBarLayer active={hasChatTabs} id="chat-tabs">
            <ChatTabs />
          </SidebarInsetBarLayer>
        </SidebarInsetBarLayers>

        <SidebarInset>
          <Outlet />
        </SidebarInset>
      </SidebarInsetFrame>

      <SidebarPanel aria-label="Matter chat" rail>
        <MatterChat />
      </SidebarPanel>
    </SidebarProvider>
  );
}

Use SidebarLayers when route state should swap the sidebar contents inside one stable sidebar shell. Each route-specific sidebar component renders the normal inner components, but it does not render another Sidebar.

import {
  SidebarContent,
  SidebarGroup,
  SidebarGroupContent,
  SidebarGroupLabel,
  SidebarLayerBackButton,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
} from "@tilt-legal/cubitt-components/sidebar";

export function SettingsSidebar() {
  return (
    <SidebarContent>
      <SidebarGroup>
        <SidebarGroupContent>
          <SidebarMenu>
            <SidebarMenuItem>
              <SidebarLayerBackButton>Back to app</SidebarLayerBackButton>
            </SidebarMenuItem>
          </SidebarMenu>
        </SidebarGroupContent>
      </SidebarGroup>

      <SidebarGroup>
        <SidebarGroupLabel>Workspace</SidebarGroupLabel>
        <SidebarGroupContent>
          <SidebarMenu>
            <SidebarMenuItem>
              <SidebarMenuButton render={<a href="/examples/settings" />}>
                <span>Members</span>
              </SidebarMenuButton>
            </SidebarMenuItem>
          </SidebarMenu>
        </SidebarGroupContent>
      </SidebarGroup>
    </SidebarContent>
  );
}

Rails And Panels

Set rail on Sidebar or SidebarLayers to keep a closed-edge target. Hovering the rail previews the closed sidebar as an overlay without changing layout. Clicking the rail toggles the real open state and shifts the layout.

Panels use the same model. The examples app keeps the chat trigger in the inset header and lets SidebarPanel own the rail hover/click behavior.

import {
  SidebarPanel,
  SidebarPanelTrigger,
} from "@tilt-legal/cubitt-components/sidebar";
import { Xmark } from "@tilt-legal/cubitt-icons/ui/outline";

export function MatterChatPanel({ enabled }: { enabled: boolean }) {
  return (
    <SidebarPanel
      aria-label="Matter chat"
      open={enabled ? undefined : false}
      rail={enabled}
    >
      <header>
        <SidebarPanelTrigger aria-label="Close matter chat" variant="ghost">
          <Xmark />
        </SidebarPanelTrigger>
      </header>
      <MatterChat />
    </SidebarPanel>
  );
}

Custom Triggers

Use useSidebar when the trigger needs app-specific rendering. The examples app uses a FeedbackButton so the primary sidebar toggle can move between the sidebar header and the inset header while still using Cubitt's sidebar state.

import { FeedbackButton } from "@tilt-legal/cubitt-components/feedback-button";
import { useSidebar } from "@tilt-legal/cubitt-components/sidebar";
import { LayoutLeft, SidebarLeft } from "@tilt-legal/cubitt-icons/ui/outline";

export function ExamplesMainSidebarTrigger() {
  const { open, toggleSidebar } = useSidebar();

  return (
    <FeedbackButton
      aria-label={open ? "Close sidebar" : "Open sidebar"}
      aria-expanded={open}
      controlled
      defaultIcon={<LayoutLeft />}
      feedbackIcon={<SidebarLeft />}
      mode="icon"
      onFeedback={toggleSidebar}
      showFeedback={open}
      variant="ghost"
    />
  );
}

Sidebar Content

Sidebar content is composed from small layout components. In the examples app the main sidebar uses a header, content groups, menu items, badges, and a footer.

import {
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarMenu,
  SidebarMenuBadge,
  SidebarMenuButton,
  SidebarMenuItem,
} from "@tilt-legal/cubitt-components/sidebar";

export function AppSidebar() {
  return (
    <>
      <SidebarHeader>
        <SidebarMenu>
          <SidebarMenuItem>
            <SidebarMenuButton isActive>
              <span>Home</span>
            </SidebarMenuButton>
          </SidebarMenuItem>
        </SidebarMenu>
      </SidebarHeader>

      <SidebarContent>
        <SidebarGroup>
          <SidebarGroupLabel>Matters</SidebarGroupLabel>
          <SidebarMenu>
            <SidebarMenuItem>
              <SidebarMenuButton>
                <span>Acme Corp Investigation</span>
              </SidebarMenuButton>
              <SidebarMenuBadge>4</SidebarMenuBadge>
            </SidebarMenuItem>
          </SidebarMenu>
        </SidebarGroup>
      </SidebarContent>

      <SidebarFooter />
    </>
  );
}

API Reference

SidebarProvider

Wraps the app shell and owns primary sidebar, mobile sidebar, panel, and rail preview state.

Prop	Type	Default	Description
`defaultOpen`	`boolean`	responsive default	Initial uncontrolled desktop sidebar state.
`open`	`boolean`	-	Controlled desktop sidebar state.
`onOpenChange`	`(open: boolean) => void`	-	Called when the desktop sidebar state changes.
`defaultPanelOpen`	`boolean`	`false`	Initial uncontrolled secondary panel state.
`panelOpen`	`boolean`	-	Controlled secondary panel state.
`onPanelOpenChange`	`(open: boolean) => void`	-	Called when the secondary panel state changes.
`children`	`React.ReactNode`	-	Sidebar, inset, and panel children.
`className`	`string`	-	Additional classes for the shell wrapper.
`style`	`React.CSSProperties`	-	Additional wrapper style, merged with sidebar CSS variables.
`...props`	`React.ComponentProps<"div">`	-	All other div attributes.

Sidebar renders one sidebar shell. SidebarLayers accepts the same props and renders route-driven SidebarLayer children inside that shell.

Prop	Type	Default	Description
`side`	`"left" \| "right"`	`"left"`	Viewport side for the sidebar.
`variant`	`"sidebar" \| "floating" \| "inset"`	`"sidebar"`	Layout treatment for the sidebar and content inset.
`collapsible`	`"offcanvas" \| "icon" \| "none"`	`"offcanvas"`	Collapse behavior.
`motion`	`"push" \| "reveal"`	`"reveal"`	Desktop open/close motion model.
`rail`	`boolean`	`false`	Enables the closed-edge hover/click rail.
`children`	`React.ReactNode`	-	Sidebar content or `SidebarLayer` children.
`className`	`string`	-	Additional classes for the sidebar container.
`...props`	`React.ComponentProps<"div">`	-	All other div attributes.

SidebarLayer

Prop	Type	Default	Description
`active`	`boolean`	`false`	Marks this layer as the visible route layer.
`onBack`	`() => void`	-	Back handler read by `SidebarLayerBackButton`.
`children`	`React.ReactNode`	-	Layer content.
`className`	`string`	-	Additional classes for the rendered layer wrapper.
`id`	`string`	-	Optional DOM id and layer context id.
`...props`	`React.ComponentProps<"div">`	-	All other div attributes.

SidebarLayerBackButton

Prop	Type	Default	Description
`children`	`React.ReactNode`	`"Back"`	Button label.
`onClick`	`React.MouseEventHandler<HTMLButtonElement>`	-	Runs before the layer `onBack`; prevent default to skip `onBack`.
`className`	`string`	-	Additional classes.
`...props`	`React.ComponentProps<typeof SidebarMenuButton>`	-	All other sidebar menu button props.

SidebarInsetFrame

Prop	Type	Default	Description
`children`	`React.ReactNode`	-	Must contain exactly one `SidebarInset`; children before it render as top bars and children after it render as bottom bars.
`className`	`string`	-	Additional classes for the frame.
`...props`	`React.ComponentProps<"div">`	-	All other div attributes.

SidebarInset

Prop	Type	Default	Description
`children`	`React.ReactNode`	-	Main page content.
`className`	`string`	-	Additional classes for the inset surface.
`...props`	`React.ComponentProps<"main">`	-	All other main attributes.

SidebarInsetBarLayers

Prop	Type	Default	Description
`children`	`React.ReactNode`	-	`SidebarInsetBarLayer` children.
`className`	`string`	-	Additional classes for the animated bar region.
`...props`	`React.ComponentProps<"div">`	-	All other div attributes.

SidebarInsetBarLayer

Prop	Type	Default	Description
`active`	`boolean`	`false`	Marks this bar layer as visible.
`children`	`React.ReactNode`	-	Bar content.
`className`	`string`	-	Additional classes for the rendered layer wrapper.
`id`	`string`	-	Optional DOM id.
`...props`	`React.ComponentProps<"div">`	-	All other div attributes.

SidebarPanel

Prop	Type	Default	Description
`side`	`"left" \| "right"`	`"right"`	Viewport side for the secondary panel.
`open`	`boolean`	provider `panelOpen`	Controlled panel state.
`width`	`string`	internal panel width	CSS width for the panel.
`motion`	`"push" \| "reveal"`	`"reveal"`	Panel open/close motion model.
`rail`	`boolean`	`false`	Enables the closed-edge panel rail.
`contentClassName`	`string`	-	Additional classes for the panel content surface.
`children`	`React.ReactNode`	-	Panel content.
`className`	`string`	-	Additional classes for the panel wrapper.
`style`	`React.CSSProperties`	-	Additional wrapper style, merged with `--sidebar-panel-width`.
`...props`	`React.ComponentProps<"aside">`	-	All other aside attributes.

SidebarPanelTrigger

Prop	Type	Default	Description
`open`	`boolean`	provider `panelOpen`	Controlled trigger state.
`onOpenChange`	`(open: boolean) => void`	-	Called with the next panel state.
`onClick`	`React.MouseEventHandler<HTMLButtonElement>`	-	Runs before the panel state changes.
`className`	`string`	-	Additional classes.
`...props`	`React.ComponentProps<typeof Button>`	-	All other Cubitt button props.

SidebarTrigger

Prop	Type	Default	Description
`children`	`React.ReactNode`	`<LayoutLeft />`	Trigger icon/content.
`onClick`	`React.MouseEventHandler<HTMLButtonElement>`	-	Runs before the sidebar state toggles; prevent default to skip the toggle.
`className`	`string`	-	Additional classes.
`...props`	`React.ComponentProps<typeof Button>`	-	All other Cubitt button props.

SidebarRail

Prop	Type	Default	Description
`side`	`"left" \| "right"`	`"left"`	Viewport side for the rail.
`onClick`	`React.MouseEventHandler<HTMLButtonElement>`	-	Runs before the sidebar toggles; prevent default to skip the toggle.
`className`	`string`	-	Additional classes.
`...props`	`React.ComponentProps<"button">`	-	All other button attributes.

SidebarInput

Prop	Type	Default	Description
`className`	`string`	-	Additional classes.
`...props`	`React.ComponentProps<typeof Input>`	-	All other Cubitt input props.

SidebarHeader, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupContent

Prop	Type	Default	Description
`children`	`React.ReactNode`	-	Section content.
`className`	`string`	-	Additional classes.
`...props`	`React.ComponentProps<"div">`	-	All other div attributes.

SidebarGroupLabel

Prop	Type	Default	Description
`render`	`React.ReactElement`	-	Element to render instead of the default `div`.
`children`	`React.ReactNode`	-	Label content.
`className`	`string`	-	Additional classes.
`...props`	`React.ComponentProps<"div">`	-	All other div attributes.

SidebarGroupAction

Prop	Type	Default	Description
`render`	`React.ReactElement`	-	Element to render instead of the default `button`.
`children`	`React.ReactNode`	-	Action content.
`className`	`string`	-	Additional classes.
`...props`	`React.ComponentProps<"button">`	-	All other button attributes.

SidebarMenu

Prop	Type	Default	Description
`children`	`React.ReactNode`	-	Menu items.
`className`	`string`	-	Additional classes.
`...props`	`React.ComponentProps<"ul">`	-	All other ul attributes.

SidebarMenuItem

Prop	Type	Default	Description
`children`	`React.ReactNode`	-	Menu item content.
`className`	`string`	-	Additional classes.
`...props`	`React.ComponentProps<"li">`	-	All other li attributes.

SidebarMenuButton

Prop	Type	Default	Description
`render`	`React.ReactElement`	-	Element to render instead of the default `button`, such as an anchor or router link.
`isActive`	`boolean`	`false`	Applies active item styling.
`variant`	`"default" \| "outline"`	`"default"`	Button visual treatment.
`size`	`"default" \| "sm" \| "lg"`	`"default"`	Button size.
`children`	`React.ReactNode`	-	Button content.
`className`	`string`	-	Additional classes.
`...props`	`React.ComponentProps<"button">`	-	All other button attributes.

SidebarMenuAction

Prop	Type	Default	Description
`render`	`React.ReactElement`	-	Element to render instead of the default `button`.
`showOnHover`	`boolean`	`false`	Hides the action until the menu item is hovered or focused on desktop.
`children`	`React.ReactNode`	-	Action content.
`className`	`string`	-	Additional classes.
`...props`	`React.ComponentProps<"button">`	-	All other button attributes.

SidebarMenuBadge

Prop	Type	Default	Description
`children`	`React.ReactNode`	-	Badge content.
`className`	`string`	-	Additional classes.
`...props`	`React.ComponentProps<"div">`	-	All other div attributes.

SidebarMenuSkeleton

Prop	Type	Default	Description
`showIcon`	`boolean`	`false`	Renders a leading icon skeleton.
`className`	`string`	-	Additional classes.
`...props`	`React.ComponentProps<"div">`	-	All other div attributes.

SidebarMenuSub

Prop	Type	Default	Description
`children`	`React.ReactNode`	-	Sub-menu items.
`className`	`string`	-	Additional classes.
`...props`	`React.ComponentProps<"ul">`	-	All other ul attributes.

SidebarMenuSubItem

Prop	Type	Default	Description
`children`	`React.ReactNode`	-	Sub-menu item content.
`className`	`string`	-	Additional classes.
`...props`	`React.ComponentProps<"li">`	-	All other li attributes.

SidebarMenuSubButton

Prop	Type	Default	Description
`render`	`React.ReactElement`	-	Element to render instead of the default anchor.
`size`	`"sm" \| "md"`	`"md"`	Button size.
`isActive`	`boolean`	`false`	Applies active item styling.
`children`	`React.ReactNode`	-	Button content.
`className`	`string`	-	Additional classes.
`...props`	`React.ComponentProps<"a">`	-	All other anchor attributes.

SidebarSeparator

Prop	Type	Default	Description
`className`	`string`	-	Additional classes.
`...props`	`React.ComponentProps<typeof Separator>`	-	All other Cubitt separator props.

useSidebar

Return	Type	Description
`state`	`"expanded" \| "collapsed"`	Derived desktop sidebar state.
`open`	`boolean`	Current desktop sidebar state.
`setOpen`	`(open: boolean) => void`	Sets the desktop sidebar state.
`openMobile`	`boolean`	Current mobile sheet state.
`setOpenMobile`	`(open: boolean) => void`	Sets the mobile sheet state.
`panelOpen`	`boolean`	Current secondary panel state.
`setPanelOpen`	`(open: boolean) => void`	Sets the secondary panel state.
`toggleSidebar`	`() => void`	Toggles desktop sidebar or mobile sheet depending on breakpoint.
`togglePanel`	`() => void`	Toggles the secondary panel.
`isMobile`	`boolean`	Whether the sidebar is currently using the mobile sheet behavior.
`sidebarPreviewActive`	`boolean`	Whether the primary sidebar rail overlay is mounted.
`setSidebarPreviewActive`	`(active: boolean) => void`	Sets primary rail overlay mount state.
`sidebarPreviewOpen`	`boolean`	Whether the primary sidebar rail overlay is open.
`setSidebarPreviewOpen`	`(open: boolean) => void`	Sets primary rail overlay visibility.
`panelPreviewActive`	`boolean`	Whether the panel rail overlay is mounted.
`setPanelPreviewActive`	`(active: boolean) => void`	Sets panel rail overlay mount state.
`panelPreviewOpen`	`boolean`	Whether the panel rail overlay is open.
`setPanelPreviewOpen`	`(open: boolean) => void`	Sets panel rail overlay visibility.

useSidebarLayer

Return	Type	Description
`id`	`string \| undefined`	Current layer id.
`index`	`number`	Current layer index.
`active`	`boolean`	Whether this layer is the visible layer.
`visible`	`boolean`	Alias for visible layer state.
`defaultLayer`	`boolean`	Whether this is the first layer.
`onBack`	`(() => void) \| undefined`	Back handler supplied to the layer.