Skip to content
WebJs
Menu

A composable, themeable and customizable sidebar component.

sidebar-07
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.

We now have a solid foundation to build on top of. Composable. Themeable. Customizable.

Browse the Blocks Library.

Installation

pnpm dlx @webjsdev/ui add sidebar

Usage

app/layout.ts
import { html } from '@webjsdev/core';
import type { LayoutProps } from '@webjsdev/core';
import { appSidebar } from '#components/app-sidebar.ts';
// Registers the sidebar's elements.
import '#components/ui/sidebar.ts';

export default function Layout({ children }: LayoutProps) {
  return html`
    <ui-sidebar-provider>
      ${appSidebar()}
      <ui-sidebar-inset>
        <ui-sidebar-trigger></ui-sidebar-trigger>
        ${children}
      </ui-sidebar-inset>
    </ui-sidebar-provider>
  `;
}
components/app-sidebar.ts
import { html } from '@webjsdev/core';
import {
  sidebarContentClass,
  sidebarFooterClass,
  sidebarGroupClass,
  sidebarHeaderClass,
} from '#components/ui/sidebar.ts';

export function appSidebar() {
  return html`
    <ui-sidebar>
      <div data-slot="sidebar-header" data-sidebar="header" class=${sidebarHeaderClass()}></div>
      <div data-slot="sidebar-content" data-sidebar="content" class=${sidebarContentClass()}>
        <div data-slot="sidebar-group" data-sidebar="group" class=${sidebarGroupClass()}></div>
        <div data-slot="sidebar-group" data-sidebar="group" class=${sidebarGroupClass()}></div>
      </div>
      <div data-slot="sidebar-footer" data-sidebar="footer" class=${sidebarFooterClass()}></div>
    </ui-sidebar>
  `;
}

appSidebar() is a fragment helper rather than an element, so the server renders the whole sidebar into the page and a reader without JavaScript still gets every link.

Composition

Use the following composition to build a sidebar layout:

<ui-sidebar-provider>
├── <ui-sidebar>
│   ├── sidebarHeaderClass()
│   ├── sidebarContentClass()
│   │   ├── sidebarGroupClass()
│   │   │   ├── sidebarGroupLabelClass()
│   │   │   ├── sidebarGroupActionClass()
│   │   │   ├── sidebarGroupContentClass()
│   │   │   └── sidebarMenuClass()
│   │   │       ├── sidebarMenuItemClass()
│   │   │       │   ├── sidebarMenuButtonClass()
│   │   │       │   ├── sidebarMenuActionClass()
│   │   │       │   └── sidebarMenuBadgeClass()
│   │   │       └── sidebarMenuItemClass()
│   │   │           ├── sidebarMenuButtonClass()
│   │   │           └── sidebarMenuSubClass()
│   │   │               ├── sidebarMenuSubItemClass()
│   │   │               └── sidebarMenuSubItemClass()
│   │   └── sidebarGroupClass()
│   │       └── sidebarMenuClass()
│   │           ├── sidebarMenuItemClass()
│   │           └── sidebarMenuItemClass()
│   ├── sidebarFooterClass()
│   └── <ui-sidebar-rail>
├── <ui-sidebar-inset>
└── <ui-sidebar-trigger>

Structure

  • <ui-sidebar-provider> holds the open state, the cookie and the keyboard shortcut, and every part inside reads it.
  • <ui-sidebar> is the main collapsible sidebar panel.
  • sidebarHeaderClass() styles the header, sticky at the top. Use it for branding, titles, or workspace switchers.
  • sidebarFooterClass() styles the footer, sticky at the bottom. Use it for user menus, settings, or actions.
  • sidebarContentClass() styles the scrollable region between the header and footer.
  • sidebarGroupClass() groups related navigation with an optional label, action, and content area.
  • sidebarMenuClass() / sidebarMenuItemClass() build the menu structure for links, badges, actions, and nested submenus.
  • <ui-sidebar-rail> is a thin strip along the sidebar's edge that toggles it.
  • <ui-sidebar-inset> wraps the main content when using the inset variant, and is the page's main landmark.
  • <ui-sidebar-trigger> is a button that toggles the sidebar open or collapsed.
<ui-sidebar>
sidebarHeaderClass() (Sticky)
sidebarContentClass() (Scrollable)
sidebarGroupClass()
sidebarGroupClass()
sidebarFooterClass() (Sticky)

SidebarProvider

The <ui-sidebar-provider> element holds the sidebar's state for every part inside it. You should always wrap your application in a <ui-sidebar-provider>.

Props

NameTypeDescription
default-open"true" or "false"Default open state of the sidebar. Render it from the sidebar_state cookie on the server so the first paint matches the reader's last choice.
openbooleanOpen state of the sidebar. Written as an attribute it wins over default-open; set as a property it opens or closes the sidebar.
ui-open-changeCustomEvent<{ open: boolean }>Fired on the provider when the sidebar opens or closes.

Width

If you have a single sidebar in your application, the widths are set where the provider and the phone sheet render, in components/ui/sidebar.ts. Edit them there.

components/ui/sidebar.ts
// The provider's wrapper: the desktop width and the collapsed icon width.
style="--sidebar-width: 16rem; --sidebar-width-icon: 3rem"

// The sheet content on a phone: --sidebar-width-mobile, else 18rem.
style="--sidebar-width: var(--sidebar-width-mobile, 18rem)"

For multiple sidebars in your application, set --sidebar-width and --sidebar-width-mobile in the style of each <ui-sidebar>. The sidebar's gap and panel read the first, and the phone sheet the second. --sidebar-width-mobile can also go on the provider, for every sidebar inside it.

<ui-sidebar-provider>
  <ui-sidebar style="--sidebar-width: 20rem; --sidebar-width-mobile: 20rem"></ui-sidebar>
</ui-sidebar-provider>

Keyboard Shortcut

To trigger the sidebar, you use the cmd+b keyboard shortcut on Mac and ctrl+b on Windows. The key is in the provider's keydown handler.

components/ui/sidebar.ts
_onKeyDown = (e: KeyboardEvent): void => {
  if (e.key === 'b' && (e.metaKey || e.ctrlKey)) {
    e.preventDefault();
    this.toggle();
  }
};

The main <ui-sidebar> element renders a collapsible sidebar. Below 768px it opens as a sheet from its side instead.

AttributeTypeDescription
sideleft or rightThe side of the sidebar.
variantsidebar, floating, or insetThe variant of the sidebar.
collapsibleoffcanvas, icon, or noneCollapsible state of the sidebar.
ValueDescription
offcanvasA collapsible sidebar that slides in from the left or right.
iconA sidebar that collapses to icons.
noneA non-collapsible sidebar.

Note: If you use the inset variant, remember to wrap your main content in a <ui-sidebar-inset> element.

<ui-sidebar-provider>
  <ui-sidebar variant="inset"></ui-sidebar>
  <ui-sidebar-inset>
    ${children}
  </ui-sidebar-inset>
</ui-sidebar-provider>

useSidebar

The provider element is the sidebar's state. From a component inside it, reach it with closest() and read or call the members below.

import type { UiSidebarProvider } from '#components/ui/sidebar.ts';

const sidebar = this.closest<UiSidebarProvider>('ui-sidebar-provider');
const { state, open, openMobile, isMobile } = sidebar;
sidebar.setOpen(false);
sidebar.setOpenMobile(true);
sidebar.toggle();
MemberTypeDescription
stateexpanded or collapsedThe current state of the sidebar.
openbooleanWhether the sidebar is open.
setOpen(open: boolean) => voidSets the open state of the sidebar, keeps it in the cookie and fires ui-open-change.
openMobilebooleanWhether the sidebar is open on mobile.
setOpenMobile(open: boolean) => voidSets the open state of the sidebar on mobile.
isMobilebooleanWhether the sidebar is on mobile.
toggle() => voidToggles the sidebar. Desktop and mobile.

SidebarHeader

Use sidebarHeaderClass() to add a sticky header to the sidebar.

components/app-sidebar.ts
<ui-sidebar>
  <div data-slot="sidebar-header" data-sidebar="header" class=${sidebarHeaderClass()}>
    <ul data-slot="sidebar-menu" data-sidebar="menu" class=${sidebarMenuClass()}>
      <li data-slot="sidebar-menu-item" data-sidebar="menu-item" class=${sidebarMenuItemClass()}>
        <ui-dropdown-menu>
          <ui-dropdown-menu-trigger>
            <button type="button" data-slot="sidebar-menu-button" data-sidebar="menu-button" class=${sidebarMenuButtonClass()}>
              Select Workspace
              ${ChevronDownIcon('ml-auto')}
            </button>
          </ui-dropdown-menu-trigger>
          <ui-dropdown-menu-content class="w-(--radix-dropdown-menu-trigger-width)">
            <ui-dropdown-menu-item>
              <span>Acme Inc</span>
            </ui-dropdown-menu-item>
          </ui-dropdown-menu-content>
        </ui-dropdown-menu>
      </li>
    </ul>
  </div>
</ui-sidebar>

SidebarFooter

Use sidebarFooterClass() to add a sticky footer to the sidebar.

<ui-sidebar>
  <div data-slot="sidebar-footer" data-sidebar="footer" class=${sidebarFooterClass()}>
    <ul data-slot="sidebar-menu" data-sidebar="menu" class=${sidebarMenuClass()}>
      <li data-slot="sidebar-menu-item" data-sidebar="menu-item" class=${sidebarMenuItemClass()}>
        <button type="button" data-slot="sidebar-menu-button" data-sidebar="menu-button" class=${sidebarMenuButtonClass()}>
          ${UserIcon()} Username
        </button>
      </li>
    </ul>
  </div>
</ui-sidebar>

SidebarContent

sidebarContentClass() styles the element that wraps the content of the sidebar. This is where you add your groups. It is scrollable.

<ui-sidebar>
  <div data-slot="sidebar-content" data-sidebar="content" class=${sidebarContentClass()}>
    <div data-slot="sidebar-group" data-sidebar="group" class=${sidebarGroupClass()}></div>
    <div data-slot="sidebar-group" data-sidebar="group" class=${sidebarGroupClass()}></div>
  </div>
</ui-sidebar>

SidebarGroup

Use sidebarGroupClass() to create a section within the sidebar.

A group has a label (sidebarGroupLabelClass()), a content area (sidebarGroupContentClass()) and an optional action (sidebarGroupActionClass()).

<div data-slot="sidebar-group" data-sidebar="group" class=${sidebarGroupClass()}>
  <div data-slot="sidebar-group-label" data-sidebar="group-label" class=${sidebarGroupLabelClass()}>Application</div>
  <button type="button" data-slot="sidebar-group-action" data-sidebar="group-action" class=${sidebarGroupActionClass()}>
    ${PlusIcon()} <span class="sr-only">Add Project</span>
  </button>
  <div data-slot="sidebar-group-content" data-sidebar="group-content" class=${sidebarGroupContentClass()}></div>
</div>

To make a group collapsible, build it on a native <details> with the collapsible helpers, its <summary> as the label. It opens and closes with no JavaScript.

<details open data-slot="collapsible" class=${cn(collapsibleClass(), 'group/collapsible')}>
  <summary data-slot="sidebar-group-label" data-sidebar="group-label" class=${cn(sidebarGroupLabelClass(), 'cursor-pointer list-none [&::-webkit-details-marker]:hidden')}>
    Help
    ${ChevronDownIcon('ml-auto transition-transform group-open/collapsible:rotate-180')}
  </summary>
  <div data-slot="collapsible-content" class=${collapsibleContentClass()}>
    <div data-slot="sidebar-group-content" data-sidebar="group-content" class=${sidebarGroupContentClass()}></div>
  </div>
</details>

SidebarMenu

sidebarMenuClass() goes on the <ul> of a menu within a group, and sidebarMenuItemClass() on each <li>.

sidebarMenuClass() on the <ul> sidebarMenuItemClass() on each <li>
sidebarMenuButtonClass()
sidebarMenuButtonClass()
sidebarMenuButtonClass()
sidebarMenuButtonClass()
the square: sidebarMenuActionClass()
<ul data-slot="sidebar-menu" data-sidebar="menu" class=${sidebarMenuClass()}>
  ${projects.map((project) => html`
    <li data-slot="sidebar-menu-item" data-sidebar="menu-item" class=${sidebarMenuItemClass()}>
      <a href=${project.url} data-slot="sidebar-menu-button" data-sidebar="menu-button" class=${sidebarMenuButtonClass()}>
        ${project.icon()}
        <span>${project.name}</span>
      </a>
    </li>
  `)}
</ul>

SidebarMenuButton

sidebarMenuButtonClass() styles a menu button within a menu item.

Put it on whatever element the item needs: an <a> for a link, a <button> for an action, the <summary> of a <details> for a collapsible item. It takes variant (default or outline) and size (default, sm or lg); set data-size to the same size.

Mark the current page's button data-active="true", and give it aria-current="page" too.

<a href="#" data-slot="sidebar-menu-button" data-sidebar="menu-button" data-active="true" aria-current="page" class=${sidebarMenuButtonClass()}>Home</a>

SidebarMenuAction

sidebarMenuActionClass() styles a menu action within a menu item. Pass showOnHover: true to keep it hidden until the item is hovered or focused.

<li data-slot="sidebar-menu-item" data-sidebar="menu-item" class=${sidebarMenuItemClass()}>
  <a href="#" data-slot="sidebar-menu-button" data-sidebar="menu-button" class=${sidebarMenuButtonClass()}>
    ${HomeIcon()}
    <span>Home</span>
  </a>
  <button type="button" data-slot="sidebar-menu-action" data-sidebar="menu-action" class=${sidebarMenuActionClass()}>
    ${PlusIcon()} <span class="sr-only">Add Project</span>
  </button>
</li>

SidebarMenuSub

sidebarMenuSubClass() styles a submenu within a menu item.

<li data-slot="sidebar-menu-item" data-sidebar="menu-item" class=${sidebarMenuItemClass()}>
  <a href="#" data-slot="sidebar-menu-button" data-sidebar="menu-button" class=${sidebarMenuButtonClass()}></a>
  <ul data-slot="sidebar-menu-sub" data-sidebar="menu-sub" class=${sidebarMenuSubClass()}>
    <li data-slot="sidebar-menu-sub-item" data-sidebar="menu-sub-item" class=${sidebarMenuSubItemClass()}>
      <a href="#" data-slot="sidebar-menu-sub-button" data-sidebar="menu-sub-button" data-size="md" class=${sidebarMenuSubButtonClass()}></a>
    </li>
  </ul>
</li>

SidebarMenuBadge

sidebarMenuBadgeClass() styles a badge within a menu item.

<li data-slot="sidebar-menu-item" data-sidebar="menu-item" class=${sidebarMenuItemClass()}>
  <a href="#" data-slot="sidebar-menu-button" data-sidebar="menu-button" class=${sidebarMenuButtonClass()}></a>
  <div data-slot="sidebar-menu-badge" data-sidebar="menu-badge" class=${sidebarMenuBadgeClass()}>24</div>
</li>

SidebarMenuSkeleton

sidebarMenuSkeleton() renders a loading placeholder for a menu item. It returns the markup itself, and takes showIcon and the text bar's width (a fixed width, since a random one would differ between the server and the browser).

<ul data-slot="sidebar-menu" data-sidebar="menu" class=${sidebarMenuClass()}>
  ${Array.from({ length: 5 }, (_, index) => html`
    <li data-slot="sidebar-menu-item" data-sidebar="menu-item" class=${sidebarMenuItemClass()}>
      ${sidebarMenuSkeleton({ width: `${60 + index * 6}%` })}
    </li>
  `)}
</ul>

SidebarTrigger

Use <ui-sidebar-trigger> to render a button that toggles the sidebar. It is named "Toggle Sidebar".

For a trigger of your own, write a component that calls the provider's toggle(). A page never runs in the browser, so the click handler has to live in a component.

import { WebComponent, html } from '@webjsdev/core';
import type { UiSidebarProvider } from '#components/ui/sidebar.ts';

class CustomTrigger extends WebComponent {
  render() {
    return html`<button type="button" @click=${() => this.closest<UiSidebarProvider>('ui-sidebar-provider')?.toggle()}>Toggle Sidebar</button>`;
  }
}
CustomTrigger.register('custom-trigger');

SidebarRail

The <ui-sidebar-rail> element renders a rail within a sidebar. This rail can be used to toggle the sidebar.

<ui-sidebar>
  <div data-slot="sidebar-header" data-sidebar="header" class=${sidebarHeaderClass()}></div>
  <div data-slot="sidebar-content" data-sidebar="content" class=${sidebarContentClass()}>
    <div data-slot="sidebar-group" data-sidebar="group" class=${sidebarGroupClass()}></div>
  </div>
  <div data-slot="sidebar-footer" data-sidebar="footer" class=${sidebarFooterClass()}></div>
  <ui-sidebar-rail></ui-sidebar-rail>
</ui-sidebar>

Controlled Sidebar

The provider keeps its own state, and you drive it from outside: write open or call setOpen() to change it, and listen for ui-open-change to follow it.

const sidebar = document.querySelector<UiSidebarProvider>('ui-sidebar-provider');

sidebar.addEventListener('ui-open-change', (e) => {
  console.log('open', e.detail.open);
});

sidebar.setOpen(false);

The choice is kept in the sidebar_state cookie, so a layout can read it on the server and render default-open to match, with no flash.

modules/layout/queries/sidebar-open.server.ts
'use server';
import { cookies } from '@webjsdev/server';

export async function sidebarOpen() {
  return cookies().get('sidebar_state')?.value !== 'false';
}
app/layout.ts
<ui-sidebar-provider default-open=${String(await sidebarOpen())}>

Theming

We use the following CSS variables to theme the sidebar.

: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);
}

Styling

Here are some tips for styling the sidebar based on different states.

<ui-sidebar collapsible="icon">
  <div data-slot="sidebar-content" data-sidebar="content" class=${sidebarContentClass()}>
    <div data-slot="sidebar-group" data-sidebar="group" class=${cn(sidebarGroupClass(), 'group-data-[collapsible=icon]:hidden')}></div>
  </div>
</ui-sidebar>
<li data-slot="sidebar-menu-item" data-sidebar="menu-item" class=${sidebarMenuItemClass()}>
  <a href="#" data-slot="sidebar-menu-button" data-sidebar="menu-button" class=${sidebarMenuButtonClass()}></a>
  <button type="button" data-slot="sidebar-menu-action" data-sidebar="menu-action" class=${cn(sidebarMenuActionClass(), 'peer-data-[active=true]/menu-button:opacity-100')}></button>
</li>

RTL

To enable RTL support, see the RTL configuration guide. Put dir="rtl" on an ancestor and give the sidebar side="right".

View RTL Sidebar

Changelog

RTL Support

Right-to-left support takes five things, and the kit's sidebar ships with all of them:

No dir prop to add.

The direction comes from the dir attribute on an ancestor, and the phone sheet inherits it.

The container carries data-side.

<ui-sidebar> sets data-side on itself and on its container.

The container is positioned by data attributes.

The container's classes use data-[side=left]: and data-[side=right]: selectors, with no ternary on the side.

The rail is positioned physically.

<ui-sidebar-rail> uses -right-4 / left-0 with ltr: and rtl: translates.

The trigger's icon flips.

<ui-sidebar-trigger>'s icon carries rtl:rotate-180.

So a right-to-left sidebar is the direction on an ancestor and the side:

<div dir="rtl">
  <ui-sidebar-provider>
    <ui-sidebar side="right"></ui-sidebar>
  </ui-sidebar-provider>
</div>

The sidebar will correctly position itself and handle interactions in both LTR and RTL layouts.