Sidebar

When to UseCopy Anchor Link

• for the main navigation of an app: the links to its sections, such as “Clients”, “Projects”, and “Invoices”
• when the sections fall into groups, each with a label such as “Sales” or “Billing”
• when a page needs the width, such as a wide table, with collapsible="icon" set

When Not to UseCopy Anchor Link

• for the main links of a marketing site (use a Navigation Menu)
• for the views of one record (use Tabs)
• for a panel that opens for one task and closes (use a Sheet)

AnatomyCopy Anchor Link

A Sidebar has a shell, which contains the page, and menus inside the shell.

ShellCopy Anchor Link

SidebarProvider wraps both halves and stores the open state. SidebarInset is the main element of the page. The figure doesn’t show SidebarRail, a strip along the outer edge of the Sidebar that users click to collapse or expand it.

MenuCopy Anchor Link

A menu is a ul, and each item is an li that contains one button, with an action or a badge at its end. A Sidebar has three more parts: SidebarInput is an Input, SidebarSeparator is a Separator between regions, and SidebarMenuSkeleton is a placeholder for an item that is loading.

VariantsCopy Anchor Link

variant on Sidebar sets how the panel meets the page.

SizesCopy Anchor Link

size on SidebarMenuButton sets the height of an item.

Use lg for a two-line button, as the preview does in its header and footer.

StatesCopy Anchor Link

To mark the item of the current page, set isActive on SidebarMenuButton. It also sets aria-current="page". To disable an item, set disabled, or aria-disabled="true" if the item is a link.

BehaviorCopy Anchor Link

From 768px, the Sidebar is positioned beside the page and is 256px wide. See Layout for the shell’s measures.

By default, side is left, which is a physical edge. In a right-to-left layout, pass side="right". See Right-to-Left for how to read the direction.

CollapsingCopy Anchor Link

collapsible on Sidebar sets what happens when the Sidebar collapses.

When the Sidebar is collapsed to icons, its parts change.

Give each button an icon as its first child, and set tooltip to its label so that users can identify a collapsed button. The Tooltip opens to the right of a collapsed button and stays hidden while the Sidebar is expanded. Sidebar doesn’t render a TooltipProvider. If there is none around the app, the Tooltip waits 600ms.

ControlsCopy Anchor Link

Below 768pxCopy Anchor Link

When useMobile reports a viewport under 768px, the Sidebar opens in a Sheet over the page. The Sidebar isn’t in the markup until the Sheet opens.

The Sheet has its own state, openMobile, which starts closed and isn’t saved to a cookie. The Sheet closes when users press Escape or click the overlay. It stays open when users click a link, so call setOpenMobile(false) when the route changes.

Saved StateCopy Anchor Link

When the state changes, SidebarProvider writes true or false to the cookie sidebar_state, which lasts seven days. SidebarProvider doesn’t read the cookie. See Restore the State for how to pass the value back.

OverflowCopy Anchor Link

When the groups are taller than the space between the header and the footer, SidebarContent scrolls, and its scrollbar is hidden. A label is truncated when it is the last span in its button.

ContentCopy Anchor Link

The Sidebar’s own labels are in labels.sidebar. To translate them, use the Summit Provider.

AccessibilityCopy Anchor Link

The parts of a Sidebar are div, ul, and li elements. Only SidebarInset, which is a main element, is a landmark.

KeyboardCopy Anchor Link

RequirementsCopy Anchor Link

No part of the Sidebar is a nav. Set role="navigation" and an aria-label such as “Main” on SidebarContent so that screen readers list the links as a landmark.

InstallationCopy Anchor Link

npx shadcn@latest add @summit/sidebar

The CLI also adds @summit/button, @summit/input, @summit/separator, @summit/sheet, @summit/skeleton, @summit/summit-provider, @summit/tooltip, and @summit/use-mobile.

UsageCopy Anchor Link

You handle these things in the application:

• The link that each item renders
• Which item is active
• The state to restore on the next visit
• Closing the Sheet after users click a link

import {
    Sidebar,
    SidebarContent,
    SidebarGroup,
    SidebarGroupContent,
    SidebarGroupLabel,
    SidebarInset,
    SidebarMenu,
    SidebarMenuButton,
    SidebarMenuItem,
    SidebarProvider,
    SidebarTrigger,
} from '@/components/ui/sidebar';
import { ReceiptIcon } from '@phosphor-icons/react';

<SidebarProvider>
    <Sidebar>
        <SidebarContent role="navigation" aria-label="Main">
            <SidebarGroup>
                <SidebarGroupLabel>Billing</SidebarGroupLabel>
                <SidebarGroupContent>
                    <SidebarMenu>
                        <SidebarMenuItem>
                            <SidebarMenuButton isActive render={<a href="/invoices" aria-current="page" />}>
                                <ReceiptIcon />
                                <span>Invoices</span>
                            </SidebarMenuButton>
                        </SidebarMenuItem>
                    </SidebarMenu>
                </SidebarGroupContent>
            </SidebarGroup>
        </SidebarContent>
    </Sidebar>
    <SidebarInset>
        <header className="flex h-12 items-center gap-2 border-b px-4">
            <SidebarTrigger />
        </header>
    </SidebarInset>
</SidebarProvider>;

Collapse to IconsCopy Anchor Link

To collapse the Sidebar to icons, set collapsible="icon" on Sidebar and tooltip on each button.

<Sidebar collapsible="icon">
    <SidebarContent>
        <SidebarMenu>
            <SidebarMenuItem>
                <SidebarMenuButton tooltip="Invoices" render={<a href="/invoices" />}>
                    <ReceiptIcon />
                    <span>Invoices</span>
                </SidebarMenuButton>
            </SidebarMenuItem>
        </SidebarMenu>
    </SidebarContent>
    <SidebarRail />
</Sidebar>

Restore the StateCopy Anchor Link

To restore the state on the next visit, read the cookie sidebar_state on the server, and pass its value to defaultOpen. In this snippet, sidebarState is that value.

<SidebarProvider defaultOpen={sidebarState !== 'false'}>
    <Sidebar />
</SidebarProvider>

Close the Sheet After a LinkCopy Anchor Link

To close the Sheet when users click a link, call setOpenMobile from the link. useSidebar returns it.

import { SidebarMenuButton, useSidebar } from '@/components/ui/sidebar';

function NavLink({ href, children }: { href: string; children: React.ReactNode }) {
    const { setOpenMobile } = useSidebar();

    return (
        <SidebarMenuButton render={<a href={href} />} onClick={() => setOpenMobile(false)}>
            {children}
        </SidebarMenuButton>
    );
}

An Action on an ItemCopy Anchor Link

To add an action to an item, place a SidebarMenuAction after the button. If you set showOnHover, the action is hidden from 768px until users hover over the item or the item has focus.

<SidebarMenuItem>
    <SidebarMenuButton render={<a href="/clients" />}>
        <UsersIcon />
        <span>Clients</span>
    </SidebarMenuButton>
    <SidebarMenuAction showOnHover aria-label="Add client">
        <PlusIcon />
    </SidebarMenuAction>
</SidebarMenuItem>

While the Menu LoadsCopy Anchor Link

While the menu loads, render a SidebarMenuSkeleton for each item. showIcon adds a square before the bar.

<SidebarMenu>
    <SidebarMenuItem>
        <SidebarMenuSkeleton showIcon />
    </SidebarMenuItem>
</SidebarMenu>

Change the WidthCopy Anchor Link

To change the width, set --sidebar-width or --sidebar-width-icon through style on SidebarProvider. Below 768px, the Sheet keeps its own width.

<SidebarProvider style={{ '--sidebar-width': '20rem' } as React.CSSProperties}>
    <Sidebar />
</SidebarProvider>

API ReferenceCopy Anchor Link

The parts accept the props of the elements they render. SidebarGroupLabel, SidebarGroupAction, SidebarMenuButton, SidebarMenuAction, and SidebarMenuSubButton also accept render. See the Base UI useRender documentation for render.

SidebarProviderCopy Anchor Link

SidebarCopy Anchor Link

SidebarMenuButtonCopy Anchor Link

SidebarMenuActionCopy Anchor Link

SidebarMenuSubButtonCopy Anchor Link

SidebarMenuSkeletonCopy Anchor Link

useSidebarCopy Anchor Link

useSidebar throws an error when it is called outside a SidebarProvider.