Advanced Components

Sidebar

A structured layout for application navigation. Includes header, body and footer areas, with small building blocks for icons, labels, badges and actions. Flexible enough for simple menus and advanced patterns like collapsible sections.

There are many block examples available that use these directives to build different sidebar patterns. Blocks are helpful when you want to see complete layouts or start from a working example.

Example

A sidebar with header, sections, badges, and a footer.

Application sidebar

<aside buiSidebar class="w-64 border-r bg-neutral-a2">
  <header buiSidebarHeader class="pb-2">
    <div class="flex items-center gap-x-2">
      <mat-icon class="size-5" svgIcon="hexagon" />
      <div class="text-sm font-semibold">Acme Inc.</div>
    </div>
  </header>

  <div buiSidebarBody>
    <div buiSidebarSection>
      <div buiSidebarSectionHeader>
        <span buiSidebarLabel>General</span>
      </div>
      <div buiSidebarSectionContent>
        <ul buiSidebarMenu>
          <li buiSidebarMenuItem>
            <div buiSidebarMenuRow>
              <button buiSidebarButton>
                <mat-icon buiSidebarIcon svgIcon="layout-dashboard" />
                <span buiSidebarLabel>Dashboard</span>
                <div buiSidebarBadge class="px-1.5">New</div>
              </button>
            </div>
          </li>
          <li buiSidebarMenuItem>
            <div buiSidebarMenuRow>
              <button buiSidebarButton>
                <mat-icon buiSidebarIcon svgIcon="folder-kanban" />
                <span buiSidebarLabel>Projects</span>
                <div buiSidebarBadge>12</div>
              </button>
            </div>
          </li>
          <li buiSidebarMenuItem>
            <div buiSidebarMenuRow>
              <button buiSidebarButton>
                <mat-icon buiSidebarIcon svgIcon="settings" />
                <span buiSidebarLabel>Settings</span>
              </button>
            </div>
          </li>
        </ul>
      </div>
    </div>

    <div buiSidebarDivider class="mx-4"></div>

    <div buiSidebarSection buiCollapsible [expanded]="true">
      <div buiSidebarSectionHeader>
        <button buiSidebarButton buiCollapsibleTrigger>
          <span buiSidebarLabel>Favorites</span>
          <mat-icon buiSidebarIcon svgIcon="chevron-right" class="transition-[rotate] group-data-[state=open]/bui-collapsible:rotate-90" />
        </button>
      </div>
      <ng-template buiCollapsiblePanel>
        <div buiCollapsibleContent>
          <div buiSidebarSectionContent>
            <ul buiSidebarMenu>
              <li buiSidebarMenuItem>
                <div buiSidebarMenuRow>
                  <button buiSidebarButton>
                    <mat-icon buiSidebarIcon svgIcon="square-kanban" />
                    <span buiSidebarLabel>Spark</span>
                  </button>
                </div>
              </li>
              <li buiSidebarMenuItem>
                <div buiSidebarMenuRow>
                  <button buiSidebarButton>
                    <mat-icon buiSidebarIcon svgIcon="calendar" />
                    <span buiSidebarLabel>Calendar</span>
                  </button>
                </div>
              </li>
            </ul>
          </div>
        </div>
      </ng-template>
    </div>
  </div>

  <footer buiSidebarFooter>
    <div class="mt-4 flex items-center gap-x-2">
      <div class="size-6 rounded-full bg-neutral-a4 ...">J</div>
      <span class="text-sm">John Doe</span>
    </div>
  </footer>
</aside>

Structure

The sidebar is fully directive-based. You compose it by applying attribute directives to standard HTML elements.

<aside buiSidebar>
  <header buiSidebarHeader>
    <!-- Logo, app name -->
  </header>

  <div buiSidebarBody>
    <div buiSidebarSection>
      <div buiSidebarSectionHeader>
        <span buiSidebarLabel>Section</span>
      </div>
      <div buiSidebarSectionContent>
        <ul buiSidebarMenu>
          <li buiSidebarMenuItem>
            <div buiSidebarMenuRow>
              <button buiSidebarButton>
                <mat-icon buiSidebarIcon svgIcon="home" />
                <span buiSidebarLabel>Home</span>
              </button>
            </div>
          </li>
        </ul>
      </div>
    </div>
  </div>

  <footer buiSidebarFooter>
    <!-- User menu, settings -->
  </footer>
</aside>

The building blocks are:

Directive	Description
`buiSidebar`	Root container. Provides the flex column layout.
`buiSidebarHeader`	Sticky header area for logo, app name, or quick actions.
`buiSidebarBody`	Scrollable area for sections and menus.
`buiSidebarFooter`	Sticky footer area for user menu or secondary actions.
`buiSidebarSection`	Groups related menu items.
`buiSidebarSectionHeader`	Header row for a section, typically contains a label and optional action.
`buiSidebarSectionContent`	Content area inside a section.
`buiSidebarMenu`	List container for menu items. Handles nested indentation automatically.
`buiSidebarMenuItem`	A single navigable row in the menu.
`buiSidebarMenuRow`	Row layout inside a menu item. Provides hover-state positioning and allows placing a button alongside actions.
`buiSidebarButton`	The clickable element inside a menu item. Handles hover and active states.
`buiSidebarIcon`	Icon aligned with the label.
`buiSidebarLabel`	Text label with truncation.
`buiSidebarBadge`	Small counter or tag.
`buiSidebarAction`	Secondary action slot (chevron, overflow menu, etc.).
`buiSidebarDivider`	Horizontal separator.
`buiSidebarSpacer`	Flexible spacer that fills available space.

buiSidebar

The root directive. Apply it to any element (typically an aside) to create a sidebar instance. It does not enforce routing or data, it is purely a layout container that groups the other sidebar pieces.

<aside buiSidebar class="w-64 border-r bg-neutral-a2">
  <!-- header, body, footer -->
</aside>

Header, Body & Footer

Three directives that structure the sidebar content. buiSidebarHeader and buiSidebarFooter are sticky by default. buiSidebarBody fills the remaining space and scrolls when content overflows.

<aside buiSidebar>
  <header buiSidebarHeader>
    <div class="flex items-center gap-x-2">
      <mat-icon svgIcon="hexagon" class="size-5" />
      <span class="text-xl font-medium">Acme Inc.</span>
    </div>
  </header>

  <div buiSidebarBody>
    <!-- Sections go here -->
  </div>

  <footer buiSidebarFooter>
    <button class="text-xs text-neutral-a11">Account</button>
  </footer>
</aside>

Section

Sections group related items within the sidebar body. A section contains an optional header and a content area with one or more menus.

<div buiSidebarSection>
  <div buiSidebarSectionHeader>
    <span buiSidebarLabel>Main</span>
  </div>

  <div buiSidebarSectionContent>
    <ul buiSidebarMenu>
      <li buiSidebarMenuItem>
        <div buiSidebarMenuRow>
          <button buiSidebarButton>
            <mat-icon buiSidebarIcon svgIcon="home" />
            <span buiSidebarLabel>Home</span>
          </button>
        </div>
      </li>
      <li buiSidebarMenuItem>
        <div buiSidebarMenuRow>
          <button buiSidebarButton>
            <mat-icon buiSidebarIcon svgIcon="inbox" />
            <span buiSidebarLabel>Inbox</span>
          </button>
        </div>
      </li>
    </ul>
  </div>
</div>

Sections do not enforce a title. You can omit the header when you do not need a visible section heading.

<ul buiSidebarMenu>
  <li buiSidebarMenuItem>
    <div buiSidebarMenuRow>
      <button buiSidebarButton>
        <mat-icon buiSidebarIcon svgIcon="square-kanban" />
        <span buiSidebarLabel>Boards</span>
      </button>
    </div>
  </li>
  <li buiSidebarMenuItem>
    <div buiSidebarMenuRow>
      <button buiSidebarButton>
        <mat-icon buiSidebarIcon svgIcon="users" />
        <span buiSidebarLabel>Team</span>
      </button>
    </div>
  </li>
</ul>

Menu item, Menu row & Button

Each menu item represents a single navigable entry. buiSidebarMenuItem is the outer container, buiSidebarMenuRow provides the row layout that positions the hover highlight and allows placing a button alongside actions, and buiSidebarButton is the clickable element. The menu row handles the ::before pseudo-element that creates the hover and active state background, and is essential for data-driven sidebars where items may include collapsible sub-menus or secondary actions.

<!-- Basic item -->
<li buiSidebarMenuItem>
  <div buiSidebarMenuRow>
    <button buiSidebarButton>
      <mat-icon buiSidebarIcon svgIcon="home" />
      <span buiSidebarLabel>Home</span>
    </button>
  </div>
</li>

<!-- Item with router link -->
<li buiSidebarMenuItem>
  <div buiSidebarMenuRow>
    <a buiSidebarButton routerLink="/projects" routerLinkActive="active">
      <mat-icon buiSidebarIcon svgIcon="square-kanban" />
      <span buiSidebarLabel>Projects</span>
    </a>
  </div>
</li>

Use a button for actions and an a for navigation links. Both work with buiSidebarButton.

Primitives

Small directives that make the sidebar structure readable and easy to style.

Icon

Apply buiSidebarIcon to a mat-icon or any element. It sizes and aligns the icon with the label.

<mat-icon buiSidebarIcon svgIcon="inbox" />

Label

Renders text with correct spacing and truncation. Use it for both section titles and item labels.

<span buiSidebarLabel>Inbox</span>

Badge

A small counter or tag displayed next to a label. Useful for unread counts or status indicators.

<li buiSidebarMenuItem>
  <div buiSidebarMenuRow>
    <button buiSidebarButton>
      <mat-icon buiSidebarIcon svgIcon="folder-kanban" />
      <span buiSidebarLabel>Projects</span>
      <div buiSidebarBadge>24</div>
    </button>
  </div>
</li>

Action

A slot for secondary actions like overflow menus or chevrons. Actions have their own hover state and can be combined with other directives like buiCollapsibleTrigger.

<li buiSidebarMenuItem>
  <div buiSidebarMenuRow>
    <button buiSidebarButton>
      <mat-icon buiSidebarIcon svgIcon="folder" />
      <span buiSidebarLabel>Projects</span>
    </button>
    <button buiSidebarAction>
      <mat-icon buiSidebarIcon svgIcon="ellipsis" />
    </button>
  </div>
</li>

Divider & Spacer

buiSidebarDivider renders a horizontal line between items. buiSidebarSpacer is a flexible spacer that pushes content apart.

<!-- Divider between items -->
<div buiSidebarDivider></div>

<!-- Spacer to push footer down -->
<div buiSidebarSpacer></div>

Collapsible section

Sections often need the ability to collapse and expand. Wrap the section in a buiCollapsible and apply buiCollapsibleTrigger to the section header button. The section content goes inside a buiCollapsiblePanel / buiCollapsibleContent pair.

Collapsible Favorites section

<div buiSidebarSection buiCollapsible [expanded]="true">
  <div buiSidebarSectionHeader>
    <button buiSidebarButton buiCollapsibleTrigger>
      <span buiSidebarLabel>Favorites</span>
      <mat-icon buiSidebarIcon svgIcon="chevron-right" class="transition-[rotate] group-data-[state=open]/bui-collapsible:rotate-90" />
    </button>
  </div>

  <ng-template buiCollapsiblePanel>
    <div buiCollapsibleContent>
      <div buiSidebarSectionContent>
        <ul buiSidebarMenu>
          <li buiSidebarMenuItem>
            <div buiSidebarMenuRow>
              <button buiSidebarButton>
                <mat-icon buiSidebarIcon svgIcon="square-kanban" />
                <span buiSidebarLabel>Projects</span>
              </button>
            </div>
          </li>
          <li buiSidebarMenuItem>
            <div buiSidebarMenuRow>
              <button buiSidebarButton>
                <mat-icon buiSidebarIcon svgIcon="calendar" />
                <span buiSidebarLabel>Calendar</span>
              </button>
            </div>
          </li>
        </ul>
      </div>
    </div>
  </ng-template>
</div>

Collapsible menu item

A single item can expand to reveal nested links. Apply buiCollapsible to the buiSidebarMenuItem and place the trigger on the buiSidebarButton. The child buiSidebarMenu inside the collapsible panel is automatically indented. This pattern works well with data-driven menus because each item independently manages its own expanded state.

Expandable menu item with nested links

<ul buiSidebarMenu>
  <li buiSidebarMenuItem>
    <div buiSidebarMenuRow>
      <button buiSidebarButton>
        <mat-icon buiSidebarIcon svgIcon="layout-dashboard" />
        <span buiSidebarLabel>Dashboard</span>
      </button>
    </div>
  </li>
  <li buiSidebarMenuItem buiCollapsible [expanded]="true">
    <div buiSidebarMenuRow>
      <button buiSidebarButton buiCollapsibleTrigger>
        <mat-icon buiSidebarIcon svgIcon="folder" />
        <span buiSidebarLabel>Projects</span>
        <mat-icon buiSidebarIcon svgIcon="chevron-right" class="transition-[rotate] group-data-[state=open]/bui-collapsible:rotate-90" />
      </button>
    </div>
    <ng-template buiCollapsiblePanel>
      <ul buiSidebarMenu buiCollapsibleContent>
        <li buiSidebarMenuItem>
          <div buiSidebarMenuRow>
            <button buiSidebarButton>
              <span buiSidebarLabel>Active</span>
            </button>
          </div>
        </li>
        <li buiSidebarMenuItem>
          <div buiSidebarMenuRow>
            <button buiSidebarButton>
              <span buiSidebarLabel>Archived</span>
            </button>
          </div>
        </li>
        <li buiSidebarMenuItem>
          <div buiSidebarMenuRow>
            <button buiSidebarButton>
              <span buiSidebarLabel>Drafts</span>
            </button>
          </div>
        </li>
      </ul>
    </ng-template>
  </li>
  <li buiSidebarMenuItem>
    <div buiSidebarMenuRow>
      <button buiSidebarButton>
        <mat-icon buiSidebarIcon svgIcon="settings" />
        <span buiSidebarLabel>Settings</span>
      </button>
    </div>
  </li>
</ul>