Sidebar

Sidebar provides application-shell navigation that collapses to an icon rail on desktop and a drawer on narrow viewports. Use a page-local menu or native nav when the navigation does not belong to the application shell.

Below 1280px the desktop sidebar collapses to its icon rail, including on mount; widening restores the state from before that collapse. A manual toggle in that range is kept, including after widening. A controlled sidebar receives these automatic changes through onOpenChange and must apply them.

Code

import {
  AppHeader,
  AppHeaderContent,
  AppHeaderLeading,
  AppLayout,
  AppLayoutContent,
  AppLayoutMain,
  LayoutDashboardIcon,
  PackageIcon,
  PageContent,
  PageHeader,
  PageHeaderTitle,
  Sidebar,
  SidebarBrand,
  SidebarContent,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
  SproutIcon,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <SidebarProvider>
      <AppLayout>
        <Sidebar>
          <SidebarBrand logo={<SproutIcon />} name="Farm operations" />

          <SidebarContent aria-label="Primary navigation">
            <SidebarMenu>
              <SidebarMenuItem>
                <SidebarMenuButton
                  icon={<LayoutDashboardIcon size={16} />}
                  render={<a href="/components/app-layout" />}
                  tooltip="Dashboard"
                >
                  Dashboard
                </SidebarMenuButton>
              </SidebarMenuItem>

              <SidebarMenuItem>
                <SidebarMenuButton
                  icon={<PackageIcon size={16} />}
                  isActive
                  render={<a aria-current="page" href="/components/sidebar" />}
                  tooltip="Orders"
                >
                  Orders
                </SidebarMenuButton>
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarContent>
        </Sidebar>

        <AppLayoutContent>
          <AppHeader>
            <AppHeaderLeading>
              <SidebarTrigger />
            </AppHeaderLeading>
            <AppHeaderContent>Orders</AppHeaderContent>
          </AppHeader>

          <AppLayoutMain>
            <PageHeader>
              <PageHeaderTitle>Open orders</PageHeaderTitle>
            </PageHeader>

            <PageContent>
              <p className="tw:text-sm tw:text-muted-foreground">
                Open orders for every location go here.
              </p>
            </PageContent>
          </AppLayoutMain>
        </AppLayoutContent>
      </AppLayout>
    </SidebarProvider>
  );
}

Custom header

SidebarHeader replaces SidebarBrand when the top of the panel needs custom content.

Code

import {
  AppHeader,
  AppHeaderLeading,
  AppLayout,
  AppLayoutContent,
  AppLayoutMain,
  PackageIcon,
  Sidebar,
  SidebarContent,
  SidebarHeader,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
  SproutIcon,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <SidebarProvider>
      <AppLayout>
        <Sidebar>
          <SidebarHeader>
            <SproutIcon size={20} />
            <span className="tw:truncate tw:text-sm tw:font-semibold">
              Prairie Grain Co-op
            </span>
          </SidebarHeader>

          <SidebarContent aria-label="Primary navigation">
            <SidebarMenu>
              <SidebarMenuItem>
                <SidebarMenuButton
                  icon={<PackageIcon size={16} />}
                  isActive
                  render={<a aria-current="page" href="/components/sidebar" />}
                  tooltip="Orders"
                >
                  Orders
                </SidebarMenuButton>
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarContent>
        </Sidebar>

        <AppLayoutContent>
          <AppHeader>
            <AppHeaderLeading>
              <SidebarTrigger />
            </AppHeaderLeading>
          </AppHeader>

          <AppLayoutMain>
            <div className="tw:flex tw:flex-1 tw:items-center tw:justify-center tw:p-5 tw:text-sm tw:text-muted-foreground">
              Open orders for every location go here.
            </div>
          </AppLayoutMain>
        </AppLayoutContent>
      </AppLayout>
    </SidebarProvider>
  );
}

Composition

SidebarProvider
└── AppLayout
    ├── Sidebar
    │   ├── SidebarBrand or SidebarHeader
    │   ├── SidebarContent
    │   │   ├── SidebarActionButton
    │   │   ├── SidebarMenu
    │   │   │   └── SidebarMenuItem
    │   │   │       ├── SidebarMenuButton
    │   │   │       ├── SidebarMenuAction
    │   │   │       ├── SidebarMenuBadge
    │   │   │       └── SidebarMenuSub
    │   │   │           └── SidebarMenuSubItem
    │   │   │               ├── SidebarMenuSubIndicator
    │   │   │               └── SidebarMenuSubButton
    │   │   └── SidebarGroup
    │   │       ├── SidebarGroupLabel
    │   │       ├── SidebarGroupAction
    │   │       └── SidebarGroupContent
    │   │           └── SidebarMenu
    │   └── SidebarFooter
    │       ├── SidebarSeparator
    │       └── SidebarUser
    └── AppLayoutContent
        └── AppHeader
            └── SidebarTrigger

Wrap the complete AppLayout, including every SidebarTrigger, in SidebarProvider. See Layout for the complete shell, grouped and nested navigation, and collapsed navigation compositions.

Collapsed navigation flyouts

Use a SidebarMenuButton flyout when a parent navigation item must expose its destinations from the collapsed desktop icon rail. This configuration-object API exists because the expanded nested menu is not rendered in that state; it is a Sidebar-specific exception, not a general alternative to Falcon’s JSX compound components.

API

Sidebar

Provides application-shell navigation as a desktop panel or mobile drawer. Renders a <div> element on desktop and accepts standard <div> props.

SidebarActionButton

Renders a primary Sidebar action as a <button> element, with optional tooltip content for its collapsed state.

Props

children

children?: React.ReactNode

Action label.

className

className?: string

CSS class applied to the action button.

icon

icon: React.ReactNode

Icon shown in the action button.

onClick

onClick?: React.MouseEventHandler<HTMLButtonElement>

Event handler called when the action button is clicked.

tooltip

tooltip?: string

Supplemental tooltip text for the collapsed desktop state.

SidebarBrand

Renders a Sidebar header containing a brand logo and optional name.

Props

logo

logo: React.ReactNode

Brand mark shown in the Sidebar header.

name

name?: React.ReactNode

Company or application name.

SidebarContent

Contains the Sidebar’s primary navigation. Renders a <nav> element and accepts standard <nav> props.

SidebarFooter

Contains account or secondary controls at the bottom of a Sidebar. Renders a <div> element and accepts standard <div> props.

SidebarGroup

Groups related Sidebar navigation items. Renders a <div> element and accepts standard <div> props.

SidebarGroupAction

Renders an action in a SidebarGroup label row as a <button> element and accepts standard <button> props. Renders nothing in the collapsed desktop sidebar.

SidebarGroupContent

Contains SidebarGroup navigation items. Renders a <div> element and accepts standard <div> props.

SidebarGroupLabel

Labels a SidebarGroup. Renders a <div> element and accepts standard <div> props.

SidebarHeader

Contains branding or controls at the top of a Sidebar. Renders a <div> element and accepts standard <div> props.

SidebarMenu

Contains Sidebar menu items. Renders a <ul> element and accepts standard <ul> props.

SidebarMenuAction

Renders an action on a SidebarMenuItem as a <button> element and accepts standard <button> props. Renders nothing in the collapsed desktop sidebar.

Props

showOnHover

showOnHover?: boolean

Whether the action is visible only while its menu item is hovered.

SidebarMenuBadge

Renders a count or status badge on a SidebarMenuItem. Renders a <div> element and accepts standard <div> props. Renders nothing in the collapsed desktop sidebar.

SidebarMenuButton

Renders a Sidebar navigation item as a <button> element by default, optionally with a collapsed-desktop flyout. Use render for navigation links.

Props

children

children?: React.ReactNode

Menu item label.

className

className?: string

CSS class applied to the menu button.

expanded

expanded?: boolean

When provided, renders a chevron indicator on the right. Manage state externally via onClick. In the mobile drawer sections are always expanded, so the button stops toggling and hides the chevron.

flyout

flyout?: SidebarMenuButtonFlyoutItem[]

Sidebar-specific collapsed-desktop flyout configuration objects. Clicking the button toggles the flyout; it is ignored in expanded mode.

icon

icon?: React.ReactNode

Icon shown before the menu button label.

isActive

isActive?: boolean

Whether the menu button represents the current location or contains it. When rendering a link, also set aria-current on the element passed to render. A button with expanded set is not marked active while its sub-menu is visible.

onClick

onClick?: React.MouseEventHandler<HTMLButtonElement>

Event handler called when the menu button is clicked, except when a collapsed flyout handles the click or a mobile parent section is expanded.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>>

Render the button as this element (e.g. an <a> for navigation) instead of a native button; the label stays in children.

tooltip

tooltip?: string

Supplemental text shown in the collapsed-desktop tooltip. This does not set the rendered element’s accessible name.

SidebarMenuItem

Wraps a Sidebar menu item and its related controls. Renders an <li> element and accepts standard <li> props.

SidebarMenuSub

Contains a nested Sidebar menu. Renders a <div> element and accepts standard <div> props when visible.

Props

expanded

expanded?: boolean

Desktop visibility, driven by the parent button’s expanded state. The mobile drawer ignores it and always shows the sub-menu.

SidebarMenuSubButton

Renders a nested Sidebar navigation item as a <button> element by default. Use render for navigation links.

Props

children

children?: React.ReactNode

Nested menu item label.

className

className?: string

CSS class applied to the nested menu button.

isActive

isActive?: boolean

Whether the nested menu button represents the current location. When rendering a link, also set aria-current on the element passed to render.

onClick

onClick?: React.MouseEventHandler<HTMLButtonElement>

Event handler called when the nested menu button is clicked.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>>

Render the button as this element (e.g. an <a> for navigation) instead of a native button; the label stays in children.

SidebarMenuSubIndicator

Renders the connector for a nested Sidebar menu item as a <div> element. It accepts no props.

SidebarMenuSubItem

Wraps a nested Sidebar menu item. Renders a <div> element and accepts standard <div> props.

SidebarProvider

Provides shared responsive state for a Sidebar and its triggers. Renders a <div> element and accepts standard <div> props.

Props

defaultOpen

defaultOpen?: boolean = true

Initial desktop expanded state for uncontrolled sidebars at viewports 1280px and wider; narrower viewports start collapsed and restore this state when widened. Defaults to true.

onOpenChange

onOpenChange?: ((open: boolean) => void)

Controlled desktop state change handler. Also called when the viewport narrows below 1280px (with false) and when it widens back (with the state from before that collapse).

open

open?: boolean

Controlled desktop expanded state.

SidebarSeparator

Separates Sidebar content regions. Renders a <div> element and accepts standard <div> props.

SidebarTrigger

Opens the mobile drawer or collapsed desktop sidebar. Renders a <button> element and accepts className and onClick from standard <button> props.

SidebarUser

Renders a Sidebar account control in a <div> element with a button that opens its menu content.

Props

menuContent

menuContent?: React.ReactNode

Content shown when the account control is opened.

name

name?: string

Full name used to render the user row and auto-generate 2-letter initials.

useSidebar

Accesses responsive Sidebar state and controls. Throws when used outside a SidebarProvider.