# Sidebar A composable, themeable and customizable sidebar component. A sidebar that collapses to icons. Sidebars are one of the most complex components to build. They are central to any application and often contain a lot of moving parts. Shad doesn't like building sidebars, so he built 30+ of them with all kinds of configurations. The core components have been extracted into `sidebar-*.svelte` files, and you can use them in your own projects. We now have a solid foundation to build on top of. Composable. Themeable. Customizable. [Browse the Blocks Library](https://shadcn-svelte.com/blocks). ## Installation Run the following command to install the `sidebar` components: ```bash pnpm dlx shadcn-svelte@latest add sidebar ``` ```bash npx shadcn-svelte@latest add sidebar ``` ```bash bun x shadcn-svelte@latest add sidebar ``` Add the following colors to your CSS file We'll go over the colors later in the [theming section](https://shadcn-svelte.com/docs/components/sidebar#theming). src/app.css ```css :root { --sidebar: oklch(0.985 0 0); --sidebar-foreground: oklch(0.145 0 0); --sidebar-primary: oklch(0.205 0 0); --sidebar-primary-foreground: oklch(0.985 0 0); --sidebar-accent: oklch(0.97 0 0); --sidebar-accent-foreground: oklch(0.205 0 0); --sidebar-border: oklch(0.922 0 0); --sidebar-ring: oklch(0.708 0 0); } .dark { --sidebar: oklch(0.205 0 0); --sidebar-foreground: oklch(0.985 0 0); --sidebar-primary: oklch(0.488 0.243 264.376); --sidebar-primary-foreground: oklch(0.985 0 0); --sidebar-accent: oklch(0.269 0 0); --sidebar-accent-foreground: oklch(0.985 0 0); --sidebar-border: oklch(1 0 0 / 10%); --sidebar-ring: oklch(0.439 0 0); } ``` ## Structure A `Sidebar` component is composed of the following parts: - `Sidebar.Provider` \- Handles collapsible state. - `Sidebar.Root` \- The sidebar container. - `Sidebar.Header` and `Sidebar.Footer` \- Sticky at the top and bottom of the sidebar. - `Sidebar.Content` \- Scrollable content. - `Sidebar.Group` \- Section within the `Sidebar.Content` . - `Sidebar.Trigger` \- Trigger for the `Sidebar` . ![Sidebar structure](/img/sidebar/sidebar-structure.png) ![Sidebar structure](/img/sidebar/sidebar-structure-dark.png) ## Usage src/routes/+layout.svelte ```svelte

{@render children?.()}

``` src/lib/components/app-sidebar.svelte ```svelte ``` ## Your First Sidebar Let's start with the most basic sidebar. A collapsible sidebar with a menu. Add a `Sidebar.Provider` and `Sidebar.Trigger` at the root of your application. src/routes/+layout.svelte ```svelte

{@render children?.()}

``` Create a new sidebar component at `src/lib/components/app-sidebar.svelte`. src/lib/components/app-sidebar.svelte ```svelte ``` Now, let's add a `Sidebar.Menu` to the sidebar. We'll use the `Sidebar.Menu` component in a `Sidebar.Group`. src/lib/components/app-sidebar.svelte ```svelte Application {#each items as item (item.title)} {#snippet child({ props })} {item.title} {/snippet} {/each} ``` You've created your first sidebar. Your first sidebar. ## Components The components in the `sidebar-*.svelte` files are built to be composable i.e you build your sidebar by putting the provided components together. They also compose well with other shadcn-svelte components such as `DropdownMenu`, `Collapsible`, `Dialog`, etc. **If you need to change the code in the `sidebar-*.svelte` files, you are encouraged to do so. The code is yours. Use the provided components as a starting point to build your own** In the next sections, we'll go over each component and how to use them. ## Sidebar.Provider The `Sidebar.Provider` component is used to provide the sidebar context to the `Sidebar` component. You should always wrap your application in a `Sidebar.Provider` component. ### Props | Name | Type | Description | | ------------------------------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `open` | `boolean` | Open state of the sidebar (bindable). | | `onOpenChange` | `(open: boolean) => void` | A callback fired *after* the open state of the sidebar changes if uncontrolled, and *before* the sidebar opens or closes if controlled. | ### Width If you have a single sidebar in your application, you can use the `SIDEBAR_WIDTH` and `SIDEBAR_WIDTH_MOBILE` constants in `src/lib/components/ui/sidebar/constants.ts` to set the width of the sidebar. src/lib/components/ui/sidebar/constants.ts ```ts export const SIDEBAR_WIDTH = "16rem"; export const SIDEBAR_WIDTH_MOBILE = "18rem"; ``` For multiple sidebars in your application, you can use the `style` prop to set the width of the sidebar. To set the width of the sidebar, you can use the `--sidebar-width` and `--sidebar-width-mobile` CSS variables in the `style` prop. ```svelte ``` This will not only handle the width of the sidebar but also the layout spacing. ### Keyboard Shortcut The `SIDEBAR_KEYBOARD_SHORTCUT` variable in `src/lib/components/ui/sidebar/constants.ts` is used to set the keyboard shortcut used to open and close the sidebar. To trigger the sidebar, you use the `cmd+b` keyboard shortcut on Mac and `ctrl+b` on Windows. You can change the keyboard shortcut by changing the value of the `SIDEBAR_KEYBOARD_SHORTCUT` variable. src/lib/components/ui/sidebar/constants.ts ```ts export const SIDEBAR_KEYBOARD_SHORTCUT = "b"; ``` ## Sidebar.Root The main `Sidebar` component used to render a collapsible sidebar. ```svelte ``` ### Props | Property | Type | Description | | ----------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `side` | `left` or `right` | The side of the sidebar. | | `variant` | `sidebar`, `floating`, or `inset` | The variant of the sidebar. | | `collapsible` | `offcanvas`, `icon`, or `none` | Collapsible state of the sidebar. | ### side Use the `side` prop to change the side of the sidebar. Available options are `left` and `right`. ```svelte ``` ### variant Use the `variant` prop to change the variant of the sidebar. Available options are `sidebar`, `floating` and `inset`. ```svelte ``` **Note:** If you use the `inset` variant, remember to wrap your main content in a `SidebarInset` component. ```svelte

``` ### collapsible Use the `collapsible` prop to make the sidebar collapsible. Available options are `offcanvas`, `icon` and `none`. ```svelte ``` | Prop | Description | | --------------------------------------- | ----------------------------------------------------------------------------------------------- | | `offcanvas` | A collapsible sidebar that slides in from the left or right. | | `icon` | A sidebar that collapses to icons. | | `none` | A non-collapsible sidebar. | ## useSidebar The `useSidebar` function is used to hook into the sidebar context. It returns a reactive class instance, so it *cannot* be destructured. Additionally, it must be called during the lifecycle of the component. ```svelte ``` | Property | Type | Description | | ------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `state` | `expanded` or `collapsed` | The current state of the sidebar. | | `open` | `boolean` | Whether the sidebar is open. | | `setOpen` | `(open: boolean) => void` | Sets the open state of the sidebar. | | `openMobile` | `boolean` | Whether the sidebar is open on mobile. | | `setOpenMobile` | `(open: boolean) => void` | Sets the open state of the sidebar on mobile. | | `isMobile` | `boolean` | Whether the sidebar is on mobile. | | `toggle` | `() => void` | Toggles the sidebar. Desktop and mobile. | ## Sidebar.Header Use the `Sidebar.Header` component to add a sticky header to the sidebar. The following example adds a `` to the `Sidebar.Header`. A sidebar header with a dropdown menu. src/lib/components/app-sidebar.svelte ```svelte {#snippet child({ props })} Select Workspace {/snippet} ``` ## Sidebar.Footer Use the `Sidebar.Footer` component to add a sticky footer to the sidebar. The following example adds a `` to the `Sidebar.Footer`. A sidebar footer with a dropdown menu. src/lib/components/app-sidebar.svelte ```svelte {#snippet child({ props })} Username {/snippet}

``` ## Sidebar.Content The `Sidebar.Content` component is used to wrap the content of the sidebar. This is where you add your `Sidebar.Group` components. It is scrollable. ```svelte ``` ## Sidebar.Group Use the `Sidebar.Group` component to create a section within the sidebar. A `Sidebar.Group` has a `Sidebar.GroupLabel`, a `Sidebar.GroupContent` and an optional `Sidebar.GroupAction`. A sidebar group. ```svelte Application ``` ## Collapsible Sidebar.Group To make a `Sidebar.Group` collapsible, wrap it in a `Collapsible`. A collapsible sidebar group. ```svelte {#snippet child({ props })} Help {/snippet} ``` **Note:** We wrap the `Collapsible.Trigger` in a `Sidebar.GroupLabel` to render a button. ## Sidebar.GroupAction Use the `Sidebar.GroupAction` component to add an action to a `Sidebar.Group`. ```svelte Projects ``` A sidebar group with an action button. ## Sidebar.Menu The `Sidebar.Menu` component is used for building a menu within a `Sidebar.Group`. A `Sidebar.Menu` is composed of `Sidebar.MenuItem`, `Sidebar.MenuButton`, `Sidebar.MenuAction`, and `Sidebar.MenuSub` components. ![Sidebar menu](/img/sidebar/sidebar-menu.png) ![Sidebar menu](/img/sidebar/sidebar-menu-dark.png) Here's an example of a `Sidebar.Menu` component rendering a list of projects. A sidebar menu with a list of projects. ```svelte Projects {#each projects as project} {#snippet child({ props })} {project.name} {/snippet} {/each} ``` ## Sidebar.MenuButton The `Sidebar.MenuButton` component is used to render a menu button within a `Sidebar.Menu`. ### Link or Anchor By default, the `Sidebar.MenuButton` renders a button, but you can use the `child` snippet to render a different component such as an `` tag. ```svelte {#snippet child({ props })} Home {/snippet} ``` ### Icon and Label You can render an icon and a truncated label inside the button. Remember to wrap the label in a `` tag. ```svelte {#snippet child({ props })} Home {/snippet} ``` ### isActive Use the `isActive` prop to mark a menu item as active. ```svelte {#snippet child({ props })} Home {/snippet} ``` ## Sidebar.MenuAction The `Sidebar.MenuAction` component is used to render a menu action within a `Sidebar.Menu`. This button works independently of the `Sidebar.MenuButton`, i.e. you can have the `Sidebar.MenuButton` as a clickable link and the `Sidebar.MenuAction` as a button. ```svelte {#snippet child({ props })} Home {/snippet} ``` ### DropdownMenu Here's an example of a `Sidebar.MenuAction` that renders a `DropdownMenu`. A sidebar menu action with a dropdown menu. ```svelte {#snippet child({ props })} Home {/snippet} {#snippet child({ props })} {/snippet} Edit Project Delete Project ``` ## Sidebar.MenuSub The `Sidebar.MenuSub` component is used to render a submenu within a `Sidebar.Menu`. Use `Sidebar.MenuSubItem` and `Sidebar.MenuSubButton` to render a submenu item. A sidebar menu sub. ```svelte ``` ## Collapsible Sidebar.Menu To make a `Sidebar.Menu` collapsible, wrap it and the `Sidebar.MenuSub` components in a `Collapsible`. A collapsible sidebar menu. ```svelte {#snippet child({ props })} {/snippet} ``` ## Sidebar.MenuBadge The `Sidebar.MenuBadge` component is used to render a badge within a `Sidebar.MenuItem`. A sidebar menu badge. ```svelte 24 ``` ## Sidebar.MenuSkeleton The `Sidebar.MenuSkeleton` component is used to render a skeleton within a `Sidebar.MenuItem`. You can use this to show a loading state while waiting for data to load. ```svelte {#each Array.from({ length: 5 }) as _, index (index)} {/each} ``` ## Sidebar.Separator The `Sidebar.Separator` component is used to render a separator within a `Sidebar`. ```svelte ``` ## Sidebar.Trigger Use the `Sidebar.Trigger` component to render a button that toggles the sidebar. The `Sidebar.Trigger` component must be used within a `Sidebar.Provider`. ```svelte

``` ## Custom Trigger To create a custom trigger, you can use the `useSidebar` hook. ```svelte ``` ## Sidebar.Rail The `Sidebar.Rail` component is used to render a rail within a `Sidebar.Root`. This rail can be used to toggle the sidebar. ```svelte ``` ## Controlled Sidebar Use Svelte's [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) to control the sidebar state. A controlled sidebar. ```svelte myOpen, (newOpen) => (myOpen = newOpen)}> ``` ## Theming We use the following CSS variables to theme the sidebar. ```css :root { --sidebar: oklch(0.985 0 0); --sidebar-foreground: oklch(0.145 0 0); --sidebar-primary: oklch(0.205 0 0); --sidebar-primary-foreground: oklch(0.985 0 0); --sidebar-accent: oklch(0.97 0 0); --sidebar-accent-foreground: oklch(0.205 0 0); --sidebar-border: oklch(0.922 0 0); --sidebar-ring: oklch(0.708 0 0); } .dark { --sidebar: oklch(0.205 0 0); --sidebar-foreground: oklch(0.985 0 0); --sidebar-primary: oklch(0.488 0.243 264.376); --sidebar-primary-foreground: oklch(0.985 0 0); --sidebar-accent: oklch(0.269 0 0); --sidebar-accent-foreground: oklch(0.985 0 0); --sidebar-border: oklch(1 0 0 / 10%); --sidebar-ring: oklch(0.439 0 0); } ``` **We intentionally use different variables for the sidebar and the rest of the application** to make it easy to have a sidebar that is styled differently from the rest of the application. Think a sidebar with a darker shade from the main application. ## Styling Here are some tips for styling the sidebar based on different states. - **Styling an element based on the sidebar collapsible state.** The following will hide the `Sidebar.Group` when the sidebar is in `icon` mode. ```svelte ``` - **Styling a menu action based on the menu button active state.** The following will force the menu action to be visible when the menu button is active. ```svelte ``` You can find more tips on using states for styling in this [Twitter thread](https://x.com/shadcn/status/1842329158879420864).