Skip to content
Components

Sidebar

BetaBeta — the props contract is close to final, but small breaking changes can still land.

Responsive app sidebar with resizing, offcanvas and icon collapse, double sidebar layers, mobile navigation, and nested menus.

Examples

Mobile bottom navigation

Below lg, SidebarMobileNav shows four primary destinations and Menu. Define destinations, icons, availability, and active state once, then render the same items with SidebarMenuButton or SidebarMobileNavItem. Sidebar mobileVariant="drawer" reuses the complete navigation in a bottom drawer, including with collapsible="none". Keep at most five visible controls, counting Menu. Desktop navigation stays in the sidebar.

Floating mobile menu

Use SidebarMobileNav variant="floating" with SidebarMobileTrigger when a persistent destination bar is not useful. The labelled Menu button opens the same complete navigation. Both presentations share SidebarProvider, support safe areas, reserve content space, and stay inside a layout="contained" preview. Keep the navigation definition and route matching in your application; use render for your router links.

Resizable sidebar

SidebarRail resizes by default: drag it or use the arrow keys. Drag below minWidth to collapse; click or press Enter to toggle. Pass resizable={false} for a rail that only toggles. SidebarProvider accepts defaultWidth or width/onWidthChange in pixels. Keep saved preferences in your application.

Right sidebar

Use side="right" for navigation on the other edge. The rail follows that edge for pointer and keyboard resizing. This example controls width through SidebarProvider.

Sheet

Sheet is the edge panel the sidebar uses on small screens, and it works on its own. SheetTrigger opens it, showCloseButton adds a close button named by closeLabel, and SheetHeader, SheetBody, and SheetFooter keep the title and actions in place while the body scrolls.

Nested navigation

Compose Collapsible with SidebarMenuButton and SidebarMenuSub for project subpages. Group labels also render CollapsibleTrigger to fold entire categories. Nested menus hide when the desktop sidebar collapses to icons.

Floating sidebar

Use variant="floating" to give the navigation its own bordered surface. On mobile it opens as an edge sheet with the same navigation.

Inset workspace

Use variant="inset" with SidebarInset to frame the content inside the workspace. Each preview contains one complete app shell; use its trigger to collapse the sidebar or open it on mobile.

Double sidebar

Compose SidebarIconRail and SidebarPanel inside one Sidebar for an icon rail beside a secondary navigation panel. Both share one collapse state, landmark, and mobile sheet: collapsible="icon" keeps the rail and hides the panel. The rail always shows icons with tooltips. layer="raised" lifts a pane onto its own card at the content level; in the inset layout it takes the content card's radius, border, and shadow. --sidebar-width sets the combined width.

Panel on the content layer

SidebarPanel layer="content" paints the panel with the SidebarInset surface. In the inset layout, the panel and the content form one card with a single outer edge; the rail stays on the sidebar surface. Collapsing the sidebar returns the content card to its own corners.

Composition

Shared mobile navigation

Declare destinations and their behavior once in the application. Render the same items for the desktop sidebar and mobile primary destinations; Menu opens the existing sidebar content. The provider shares visibility, while the application owns route selection.

  • <SidebarProvider>
    • <Sidebar>
      • mobileVariant="drawer"; complete navigation
        • <SidebarContent>
          • <SidebarMenu />
          </SidebarContent>
      </Sidebar>
    • <SidebarInset>
      • route content
      </SidebarInset>
    • <SidebarMobileNav>
      • <SidebarMobileNavItem />
      • <SidebarMobileTrigger />
      </SidebarMobileNav>
    </SidebarProvider>

Application shell

  • <SidebarProvider>
    • <Sidebar>
      • <SidebarHeader />
      • <SidebarContent>
        • <SidebarGroup>
          • <SidebarGroupLabel />
          • <SidebarGroupContent>
            • <SidebarMenu>
              • <SidebarMenuItem>
                • <SidebarMenuButton />
                • <SidebarMenuBadge />
                • <SidebarMenuAction />
                • <SidebarMenuSub>
                  • <SidebarMenuItem>
                    • <SidebarMenuButton />
                    </SidebarMenuItem>
                  </SidebarMenuSub>
                </SidebarMenuItem>
              </SidebarMenu>
            </SidebarGroupContent>
          </SidebarGroup>
        </SidebarContent>
      • <SidebarFooter />
      • <SidebarRail />
      </Sidebar>
    • <SidebarInset>
      • <SidebarTrigger />
      </SidebarInset>
    </SidebarProvider>

Collapsible navigation group

  • <SidebarProvider>
    • <Sidebar>
      • <SidebarContent>
        • <SidebarGroup>
          • <SidebarMenu>
            • <SidebarMenuItem>
              • <Collapsible>
                • <SidebarMenuButton>
                  • render prop
                    • <CollapsibleTrigger />
                  </SidebarMenuButton>
                • <CollapsibleContent>
                  • <SidebarMenuSub>
                    • <SidebarMenuItem>
                      • <SidebarMenuButton />
                      </SidebarMenuItem>
                    </SidebarMenuSub>
                  </CollapsibleContent>
                </Collapsible>
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarGroup>
        </SidebarContent>
      </Sidebar>
    </SidebarProvider>

Double sidebar

One Sidebar holds both panes, so they share one landmark, collapse state, and mobile sheet. The icon rail always shows icons with tooltips; collapsible="icon" keeps it and hides the panel. layer places each pane on the sidebar surface, its own raised card, or (for the panel) the content card.

  • <SidebarProvider>
    • <Sidebar>
      • <SidebarIconRail>
        • layer="raised"; sections
          • <SidebarContent>
            • <SidebarMenu>
              • <SidebarMenuItem>
                • <SidebarMenuButton />
                </SidebarMenuItem>
              </SidebarMenu>
            </SidebarContent>
        </SidebarIconRail>
      • <SidebarPanel>
        • layer="content"; pages of the selected section
          • <SidebarHeader />
          • <SidebarContent>
            • <SidebarGroup />
            </SidebarContent>
        </SidebarPanel>
      </Sidebar>
    • <SidebarInset>
      • <SidebarTrigger />
      </SidebarInset>
    </SidebarProvider>

Installation

The Control UI source installs this component from src/registry/sources/control-ui/ui/sidebar.tsx.

Registry command
See registry manifest

Dependencies

Mobile hooksrc/registry/hooks/use-mobile.tsHook
Sidebar menussrc/registry/sources/control-ui/ui/sidebar-menu.tsxSupport
Mobile navigationsrc/registry/sources/control-ui/ui/sidebar-mobile.tsxSupport
Sidebar statesrc/registry/sources/control-ui/ui/sidebar-provider.tsxSupport
Sidebar resizingsrc/registry/sources/control-ui/ui/sidebar-resize-rail.tsxSupport
Sheet slotsrc/registry/sources/control-ui/ui/sheet.tsxSkin
ButtonbuttonComponentDrawerdrawerComponentScroll areascroll-areaComponentTooltiptooltipComponentTrack highlighttrack-highlightComponent

Raw code

Primary installed source

src/registry/sources/control-ui/ui/sidebar.tsx

Knobs

Typed custom properties the recipe paints with. Set one on the root — style, a utility class, or a skin — and every slot inherits it.

--cui-sidebar-* · 75 knobsHow the cascade resolves
--cui-sidebar-nav-height<length-percentage>4.5rem
--cui-sidebar-nav-background<color>var(--sidebar)
--cui-sidebar-nav-foreground<color>var(--sidebar-foreground)
--cui-sidebar-nav-border-color<color>var(--sidebar-border)
--cui-sidebar-nav-border-width<length>var(--control-rim-width)
--cui-sidebar-nav-shadow*var(--shadow-md)
--cui-sidebar-nav-item-radius<length-percentage>var(--radius-control)
--cui-sidebar-nav-item-active-background<color>var(--active-fill)
--cui-sidebar-nav-item-active-foreground<color>var(--foreground)
--cui-sidebar-nav-gap<length-percentage>calc(var(--spacing) * 3)
--cui-sidebar-icon-rail-border-width<length>1px
--cui-sidebar-icon-rail-border-color<color>var(--sidebar-border)
--cui-sidebar-raised-background<color>var(--cui-sidebar-inset-background)
--cui-sidebar-raised-border-width<length>var(--cui-sidebar-inset-border-width)
--cui-sidebar-raised-border-color<color>var(--cui-sidebar-inset-border-color)
--cui-sidebar-raised-radius<length-percentage>var(--cui-sidebar-inset-radius)
--cui-sidebar-raised-shadow*var(--cui-sidebar-inset-shadow)
--cui-sidebar-inner-floating-border-width<length>var(--control-rim-width)
--cui-sidebar-inner-floating-radius<length-percentage>var(--radius-panel)
--cui-sidebar-inner-floating-shadow*var(--shadow-md)
--cui-sidebar-skip-link-background<color>var(--background)
--cui-sidebar-skip-link-foreground<color>var(--foreground)
--cui-sidebar-skip-link-radius<length-percentage>var(--radius-control)
--cui-sidebar-skip-link-shadow*var(--shadow-md)
--cui-sidebar-menu-badge-height<length-percentage>calc(var(--spacing) * 5)
--cui-sidebar-menu-badge-background<color>oklch(from var(--sidebar-foreground) l c h / 0.08)
--cui-sidebar-menu-badge-foreground<color>var(--sidebar-foreground)
--cui-sidebar-header-border-width<length>1px
--cui-sidebar-header-border-color<color>var(--sidebar-border)
--cui-sidebar-rail-divider-background<color>transparent
--cui-sidebar-menu-badge-radius<length-percentage>9999px
--cui-sidebar-menu-button-icon-foreground<color>currentColor
--cui-sidebar-menu-button-active-icon-foreground<color>currentColor
--cui-sidebar-menu-button-background<color>transparent
--cui-sidebar-menu-button-shadow*0 0 transparent
--cui-sidebar-wrapper-background<color>transparent
--cui-sidebar-wrapper-background-image*none
--cui-sidebar-inner-background<color>var(--sidebar)
--cui-sidebar-inner-border-color<color>var(--sidebar-border)
--cui-sidebar-inner-background-image*none
--cui-sidebar-inner-backdrop-filter*none
--cui-sidebar-container-border-width<length>1px
--cui-sidebar-inner-border-width<length>0px
--cui-sidebar-inner-radius<length-percentage>0px
--cui-sidebar-inner-shadow*0 0 transparent
--cui-sidebar-header-background<color>transparent
--cui-sidebar-header-shadow*0 0 transparent
--cui-sidebar-inset-background<color>var(--background)
--cui-sidebar-inset-background-image*none
--cui-sidebar-inset-shadow*var(--shadow-sm)
--cui-sidebar-inset-border-color<color>var(--sidebar-border)
--cui-sidebar-inset-border-width<length>0px
--cui-sidebar-inset-radius<length-percentage>var(--radius-xl)
--cui-sidebar-inset-inset<length-percentage>calc(var(--spacing) * 2)
--cui-sidebar-menu-button-radius<length-percentage>var(--radius-popup-item)
--cui-sidebar-group-label-foreground<color>oklch(from var(--sidebar-foreground) l c h / 0.7)
--cui-sidebar-menu-button-foreground<color>var(--sidebar-foreground)
--cui-sidebar-menu-button-hover-background<color>var(--hover-fill)
--cui-sidebar-menu-button-hover-foreground<color>var(--foreground)
--cui-sidebar-menu-button-hover-shadow*0 0 transparent
--cui-sidebar-menu-button-active-background<color>var(--active-fill)
--cui-sidebar-menu-button-active-foreground<color>var(--foreground)
--cui-sidebar-menu-button-active-shadow*0 0 transparent
--cui-sidebar-menu-button-track-active-foreground<color>var(--foreground)
--cui-sidebar-menu-button-height<length-percentage>var(--control-h-md)
--cui-sidebar-menu-button-padding-block<length-percentage>0px
--cui-sidebar-menu-button-padding-inline<length-percentage>calc(var(--sidebar-width-icon) / 2 - var(--spacing) * 4)
--cui-sidebar-menu-button-font-size<length-percentage>var(--text-body)
--cui-sidebar-menu-button-font-weight<number>var(--font-weight-normal)
--cui-sidebar-menu-button-active-font-weight<number>var(--font-weight-medium)
--cui-sidebar-group-label-font-size<length-percentage>var(--text-caption)
--cui-sidebar-group-label-font-weight<number>var(--font-weight-medium)
--cui-sidebar-group-label-letter-spacing<length>0em
--cui-sidebar-group-label-text-transformnone | uppercase | lowercase | capitalizenone
--cui-sidebar-group-label-padding<length-percentage>+0px calc(var(--spacing) * 2)