Sidebar

Collapsible navigation sidebar with grouped sections, heading labels, and active link highlighting. Ideal for documentation sites, admin panels, and any layout that needs persistent vertical navigation.

Components

Sidebar

navigation

hybrid

<arc-sidebar>

Overview

Sidebar provides a structured vertical navigation panel that organizes links into collapsible, headed sections. It is the standard way to present multi-level navigation in documentation sites, admin dashboards, settings panels, and any application where the user needs to move between many related pages without losing context. Each SidebarSection groups links under an optional heading, creating a clear visual hierarchy that mirrors your information architecture. The active prop on SidebarLink highlights the current page, giving users an immediate sense of where they are within the navigation tree. An `icon` on a section renders before its heading. **Collapsing is opt-in and has an imperative half.** A section is a static group until you set `collapsible`, which turns its heading into a toggle button; `open` then controls whether the links are showing, and defaults to expanded (`no-open` starts it collapsed). Either state change fires `arc-toggle` with `{ open }` in the detail. You can drive it from script with `section.toggle()` — which is how you expand the section containing the current route on load, or collapse everything but one. It fires the same event the header does, so a listener sees both paths identically. Note that it is a deliberate no-op on a section without `collapsible`: a section whose header offers no way back would otherwise be collapsible from script into a state the user cannot undo. Sidebar is designed to sit inside an AppShell or PageLayout, typically occupying the left rail. It reads the full viewport height by default and scrolls independently of the main content area, so deep navigation trees remain accessible even on long pages. Pair it with TopBar for a complete application chrome.

Guidelines

When to use

Group related links under a SidebarSection with a descriptive heading
Set the active prop on the link that matches the current route
Call `toggle()` on the section holding the active route at page load, so a deep link arrives with its group already open
Keep section headings short — one to three words that name the category
Place the Sidebar inside an AppShell or PageLayout for consistent layout
Use a Drawer to present the Sidebar on narrow viewports
Order sections by importance or frequency of use, most common first

When not to use

Do not nest Sidebars inside each other — use sections and indentation instead
Do not mark more than one link as active at the same time
Do not expect `toggle()` to do anything on a section without `collapsible` — it deliberately no-ops rather than hiding links behind a header that cannot bring them back
Do not use Sidebar for top-level site-wide navigation — prefer TopBar for that role
Do not add more than eight to ten links per section; split large groups into sub-sections
Do not omit headings on sections — unlabeled groups make navigation harder to scan
Do not place actions (buttons, toggles) inside the Sidebar — it is for navigation links only

Features

Collapsible sections with heading labels for grouped navigation
`toggle()` on a section expands or collapses it from script, firing `arc-toggle` exactly as the header does
`arc-toggle` carries `{ open }` and bubbles, so one listener on the sidebar covers every section
Active link highlighting to indicate the current page
Independent scroll region for deep navigation trees
Composable with SidebarSection and SidebarLink sub-components
Keyboard navigable with focus-visible indicators on every link
Designed to integrate with AppShell and PageLayout for full-page chrome
Responsive-ready — pairs with Drawer for mobile breakpoints
Token-driven theming for background, border, and active-link colors

Preview

Getting Started

Design Tokens

Theming

Button

Card

Modal

Alert

Toast

Usage

Layout and styling work without JavaScript via the HTML/CSS versions. Interactive features like events and state management require the Web Component or a framework wrapper.

<script type="module" src="@arclux/arc-ui"></script>

<arc-sidebar>
  <arc-sidebar-section heading="Guide">
    <arc-sidebar-link href="/docs/getting-started">Getting Started</arc-sidebar-link>
    <arc-sidebar-link href="/docs/tokens">Design Tokens</arc-sidebar-link>
    <arc-sidebar-link href="/docs/theming" active>Theming</arc-sidebar-link>
  </arc-sidebar-section>
  <arc-sidebar-section heading="Components">
    <arc-sidebar-link href="/docs/components/button">Button</arc-sidebar-link>
    <arc-sidebar-link href="/docs/components/card">Card</arc-sidebar-link>
    <arc-sidebar-link href="/docs/components/modal">Modal</arc-sidebar-link>
  </arc-sidebar-section>
</arc-sidebar>

import { Sidebar, SidebarSection, SidebarLink } from '@arclux/arc-ui-react';

export function DocsSidebar() {
  return (
    <Sidebar>
      <SidebarSection heading="Guide">
        <SidebarLink href="/docs/getting-started">Getting Started</SidebarLink>
        <SidebarLink href="/docs/tokens">Design Tokens</SidebarLink>
        <SidebarLink href="/docs/theming" active>Theming</SidebarLink>
      </SidebarSection>
      <SidebarSection heading="Components">
        <SidebarLink href="/docs/components/button">Button</SidebarLink>
        <SidebarLink href="/docs/components/card">Card</SidebarLink>
        <SidebarLink href="/docs/components/modal">Modal</SidebarLink>
      </SidebarSection>
    </Sidebar>
  );
}

<script setup>
import { Sidebar, SidebarSection, SidebarLink } from '@arclux/arc-ui-vue';
</script>

<template>
  <Sidebar>
    <SidebarSection heading="Guide">
      <SidebarLink href="/docs/getting-started">Getting Started</SidebarLink>
      <SidebarLink href="/docs/tokens">Design Tokens</SidebarLink>
      <SidebarLink href="/docs/theming" active>Theming</SidebarLink>
    </SidebarSection>
    <SidebarSection heading="Components">
      <SidebarLink href="/docs/components/button">Button</SidebarLink>
      <SidebarLink href="/docs/components/card">Card</SidebarLink>
      <SidebarLink href="/docs/components/modal">Modal</SidebarLink>
    </SidebarSection>
  </Sidebar>
</template>

<script>
  import { Sidebar, SidebarSection, SidebarLink } from '@arclux/arc-ui-svelte';
</script>

<Sidebar>
  <SidebarSection heading="Guide">
    <SidebarLink href="/docs/getting-started">Getting Started</SidebarLink>
    <SidebarLink href="/docs/tokens">Design Tokens</SidebarLink>
    <SidebarLink href="/docs/theming" active>Theming</SidebarLink>
  </SidebarSection>
  <SidebarSection heading="Components">
    <SidebarLink href="/docs/components/button">Button</SidebarLink>
    <SidebarLink href="/docs/components/card">Card</SidebarLink>
    <SidebarLink href="/docs/components/modal">Modal</SidebarLink>
  </SidebarSection>
</Sidebar>

import { Component } from '@angular/core';
import { Sidebar, SidebarSection, SidebarLink } from '@arclux/arc-ui-angular';

@Component({
  imports: [Sidebar, SidebarSection, SidebarLink],
  template: `
    <arc-sidebar>
      <arc-sidebar-section heading="Guide">
        <arc-sidebar-link href="/docs/getting-started">Getting Started</arc-sidebar-link>
        <arc-sidebar-link href="/docs/tokens">Design Tokens</arc-sidebar-link>
        <arc-sidebar-link href="/docs/theming" active>Theming</arc-sidebar-link>
      </arc-sidebar-section>
      <arc-sidebar-section heading="Components">
        <arc-sidebar-link href="/docs/components/button">Button</arc-sidebar-link>
        <arc-sidebar-link href="/docs/components/card">Card</arc-sidebar-link>
        <arc-sidebar-link href="/docs/components/modal">Modal</arc-sidebar-link>
      </arc-sidebar-section>
    </arc-sidebar>
  `,
})
export class DocsSidebarComponent {}

import { Sidebar, SidebarSection, SidebarLink } from '@arclux/arc-ui-solid';

export function DocsSidebar() {
  return (
    <Sidebar>
      <SidebarSection heading="Guide">
        <SidebarLink href="/docs/getting-started">Getting Started</SidebarLink>
        <SidebarLink href="/docs/tokens">Design Tokens</SidebarLink>
        <SidebarLink href="/docs/theming" active>Theming</SidebarLink>
      </SidebarSection>
      <SidebarSection heading="Components">
        <SidebarLink href="/docs/components/button">Button</SidebarLink>
        <SidebarLink href="/docs/components/card">Card</SidebarLink>
        <SidebarLink href="/docs/components/modal">Modal</SidebarLink>
      </SidebarSection>
    </Sidebar>
  );
}

import { Sidebar, SidebarSection, SidebarLink } from '@arclux/arc-ui-preact';

export function DocsSidebar() {
  return (
    <Sidebar>
      <SidebarSection heading="Guide">
        <SidebarLink href="/docs/getting-started">Getting Started</SidebarLink>
        <SidebarLink href="/docs/tokens">Design Tokens</SidebarLink>
        <SidebarLink href="/docs/theming" active>Theming</SidebarLink>
      </SidebarSection>
      <SidebarSection heading="Components">
        <SidebarLink href="/docs/components/button">Button</SidebarLink>
        <SidebarLink href="/docs/components/card">Card</SidebarLink>
        <SidebarLink href="/docs/components/modal">Modal</SidebarLink>
      </SidebarSection>
    </Sidebar>
  );
}

<arc-sidebar>
  <arc-sidebar-section heading="Guide">
    <arc-sidebar-link href="/docs/getting-started">Getting Started</arc-sidebar-link>
    <arc-sidebar-link href="/docs/tokens">Design Tokens</arc-sidebar-link>
    <arc-sidebar-link href="/docs/theming" active>Theming</arc-sidebar-link>
  </arc-sidebar-section>
  <arc-sidebar-section heading="Components">
    <arc-sidebar-link href="/docs/components/button">Button</arc-sidebar-link>
    <arc-sidebar-link href="/docs/components/card">Card</arc-sidebar-link>
    <arc-sidebar-link href="/docs/components/modal">Modal</arc-sidebar-link>
  </arc-sidebar-section>
</arc-sidebar>

<!-- arc-sidebar is hybrid — CSS handles layout, JS enhances interactivity -->
<arc-sidebar></arc-sidebar>

API

active string ='': The href of the currently active sidebar link. Used to highlight the matching link with accent styling.
width string ='': Width of the sidebar. Accepts any CSS length value. Unset by default, which lets the rail fill whatever container it is placed in — including arc-app-shell, whose own rail is 280px wide and reads --sidebar-width. Set this only for a standalone sidebar; inside the shell the wrapper wins, and the token is the way to move both together.
label string ='Sidebar navigation'
position 'left' | 'right' ='left': Controls which side the sidebar appears on. Moves the border line to the opposite edge.
collapsed boolean =false: When true, collapses the sidebar away entirely: width 0 with its contents clipped, which is the right behaviour for a rail that slides out of the way but is not an icon-only mode. For a persistent icon rail — the VS Code activity-bar shape — use arc-rail, which is a different component with its own labels and tooltips.
glow boolean =false: Enables an accent glow effect on the active sidebar link for enhanced visual emphasis.

Events

arc-navigate: Fired when a sidebar link is clicked

SidebarSection

<arc-sidebar-section>

A collapsible group within a Sidebar. Each section renders an optional heading label above its child links, creating a visual and semantic grouping that mirrors your information architecture. Fires an `arc-toggle` event with `{ open }` detail when the section is expanded or collapsed.

links: Get child arc-sidebar-link elements
heading string ='': Text label displayed above the group of links. Keep it short (one to three words) so the sidebar stays scannable. When omitted, links render without a heading divider.
icon string ='': Name of an icon to render before the heading. Ignored when the section has no heading.
collapsible boolean =false: When true, the section heading becomes a toggle button that expands/collapses the child links.
open boolean =true: Controls whether a collapsible section is expanded (true) or collapsed (false). Only relevant when collapsible is true.

Methods

toggle(): Collapse an open section or expand a collapsed one, firing arc-toggle. A no-op unless collapsible is set: a section that cannot collapse has nothing to toggle, and silently doing nothing is better than a state the header offers no way back from.

Events

arc-toggle detail: { open: boolean }: Fired when a collapsible section expands or collapses.

SidebarLink

<arc-sidebar-link>

A navigation link rendered inside a SidebarSection. Supports an active state to indicate the current page and provides focus-visible styling for keyboard navigation.

resolvedHref: Destination, preferring the explicit attribute over an anchor child. Authoring <arc-sidebar-link><a href="/docs">Docs</a></arc-sidebar-link> leaves a working link in the pre-upgrade markup — arc-sidebar hides this light DOM only once it has re-rendered it into shadow DOM.
label: textContent already reaches through an anchor child, so this needs no special case.
href string ='': Destination URL for the link. Can be an absolute path, relative path, or hash anchor. The link renders as a standard anchor element for full accessibility and SEO.
level number =0: Nesting depth for visual indentation. Level 0 links render at default size; level 1+ links are indented and use a smaller font size.
icon string ='': Name of an icon to render before the label. Use icons consistently within a section — a sidebar where only some links carry one reads as an oversight rather than a hierarchy.
active boolean =false: When true, applies a highlighted style (accent-colored text and a left-edge indicator) to signal that this link corresponds to the currently viewed page. Only one link should be active at a time.
external boolean =false: Marks a destination that leaves the surrounding section — an app on its own route, another site, a repository. The link gains a persistent box-arrow glyph in place of the hover chevron, so the departure is legible before the click rather than after it.

Sidebar

Overview

Guidelines

When to use

When not to use

Features

Preview

Usage

API

Events

SidebarSection

Methods

Events

SidebarLink

See Also

Docs

Project

Arclight