Skip to content

Sidebar ​

A collapsible navigation sidebar with labelled groups and individual items. It uses the same frosted panel surface treatment as the drawer, while still supporting icon-only collapse mode, keyboard navigation, and full ARIA compliance. On small screens it switches to a bottom tab bar plus an overlay drawer with tap-to-dismiss, a close button, and swipe-to-dismiss.

Collapsible Sidebar ​

Add the collapsible attribute to show the collapse control. Sidebars with a logo anchor it to the panel edge; text-only sidebars keep it inside the header so collapsed mode has no empty logo space. It uses panel-left-close when expanded and panel-left-open when collapsed. Header height and padding remain fixed across both states. Items animate to icon-only mode while their labels remain in the accessibility tree and keyboard reachable. Pair collapsed items with ore-tooltip to surface labels for sighted keyboard and pointer users.

Full width

Responsive App Shell (Desktop / Tablet / Mobile) ​

Use two breakpoints to get the full three-state behavior:

  • Desktop: full sidebar, collapsed from a navbar button (toggle())
  • Tablet: compact/collapsed sidebar (responsive)
  • Mobile: bottom navigation + drawer (bottom-nav-at), opened from the same navbar control (menu-icon="panel-left-open") and closed by backdrop tap, swipe, Escape, or the control again

The navbar owns the chrome in an app shell: the sidebar keeps no header of its own (branding lives in the navbar) and no built-in toggle (drop collapsible; the navbar button calls sidebar.toggle() instead).

Full width

Integration Notes ​

  • By default, bottom navigation tabs are derived from direct ore-sidebar-item children.
  • For grouped sidebars, mark any descendant item with bottom-nav to promote it. Once one item is marked, only marked items appear in the bottom bar.
  • Use bottom-nav-label when the mobile tab needs a shorter label than the desktop item.
  • Use label to give an item's internal link or button an explicit accessible name, especially in collapsed icon-only navigation.
  • ore-sidebar-group content remains available in the drawer opened by openDrawer() or a linked ore-navbar mobile-sidebar trigger.
  • In an app shell with a navbar, omit collapsible and the sidebar header/logo slots: the navbar carries branding and its own button drives toggle(), so the sidebar shows navigation only. Give the navbar menu-icon="panel-left-open" and the mobile drawer control reads as the same control as the desktop one; the headerless drawer opens straight into the navigation, matching the desktop and tablet layout.
  • Use responsive for tablet compact mode and bottom-nav-at for mobile bottom-nav mode.
  • The bottom bar is an overlay: give scrollable page content bottom clearance (--sidebar-bottom-nav-height) in the mobile breakpoint so the last items are reachable.

Drawer Behavior ​

When the sidebar enters bottom-nav mode (or you call openDrawer()), the panel becomes an overlay: background content becomes inert and focus is trapped inside the drawer until it closes. The page behind it is left undimmed by default — a navigation drawer slides in from the edge you just tapped and is meant to be read against its content, and the panel's own elevation carries the separation. Opt into a dimming scrim with backdrop (below) when you want the modal treatment.

The drawer offers three ways to dismiss it, covering touch, pointer, and keyboard:

  • Backdrop tap — clicking outside the panel closes the drawer.
  • Close button — when the sidebar has header content, an × button appears in the drawer header, in the same row position the collapse toggle holds on desktop, labelled by drawer-close-label. A sidebar without header content (the app-shell pattern above) keeps the drawer headerless so the panel matches its desktop and tablet layout; it closes through the other routes.
  • Swipe — dragging the grabber nub on the panel's trailing edge past a threshold closes the drawer; releasing early snaps back.

Closing or reopening cancels an in-progress swipe and clears its visual offset. A second touch also cancels the swipe, and pinch zoom remains available over the handle. The sidebar does not claim swipes from the navigation content.

Escape also closes the drawer, and focus returns to the element that opened it. Selecting a navigation item closes the drawer by default; set close-on-select="false" to keep it open.

The backdrop is click-to-close only by default. backdrop="opaque" dims the page with the theme scrim and backdrop="blur" adds a blur behind the panel; both are built from the theme's darkening veil, so they dim in either light or dark scheme rather than inverting into a bright fog. backdrop="transparent" is the same as the default. The values match ore-drawer, whose backdrop dims by default because a dialog replaces the page rather than sliding in beside it.

html
<ore-sidebar bottom-nav-at="(max-width: 640px)" backdrop="blur" drawer-close-label="Close navigation">
  <!-- ... -->
</ore-sidebar>

In drawer-only mode the sidebar has no inline panel and no bottom bar: it exists solely as the API/navbar-driven overlay drawer, with the same backdrop, close button, and swipe behavior.

Groups ​

Use ore-sidebar-group to organize items into labelled sections. Add the collapsible attribute to allow toggling the group open/closed.

ore-sidebar-group uses native details/summary semantics internally: the header is a real summary, so keyboard activation (Enter/Space), focus, and the disclosed-region relationship come from the browser. Collapsible headers carry aria-expanded reflecting the real open state, and toggling an uncontrolled group emits open-change with { open }.

Set default-open="false" for uncontrolled groups that start collapsed, or pass open to control the group state externally. While open is set, the prop is the single source of truth: header clicks no longer change the state until the attribute is removed.

An uncontrolled collapsible group opens itself when one of its items is (or becomes) active, so a deep-linked page never starts with the current location folded away. It reopens only on a fresh activation: collapsing the group while its item stays active is respected. Auto-expansion emits the same open-change event as a manual toggle.

The group header takes an end slot for trailing content such as a count badge.

Use ore-sidebar-group to group semantically related items: it adds a visible label and an implicit role="list" on the items container. Avoid setting active on more than one item simultaneously, as it breaks aria-current semantics.

Full width

Collapsed Label Bubble ​

When the sidebar is collapsed to its icon rail, labels are hidden. Hovering or focusing an item then shows the label as a small bubble next to the rail. The bubble is fixed-position, so scroll containers and overflow: hidden wrappers cannot clip it, and it mirrors the reading side in RTL.

Full width

Style it with --sidebar-item-reveal-bg, --sidebar-item-reveal-color, --sidebar-item-reveal-radius, and --sidebar-item-reveal-shadow. Screen readers already receive the full label from the item itself; the bubble is a sighted-user affordance and carries aria-hidden.

Items with Badges ​

Use the end slot on ore-sidebar-item for trailing content such as notification counts or keyboard shortcuts.

Full width

Variants ​

Floating ​

Uses the same drawer-inspired panel surface with a stronger floating presentation, rounded corners, and more separation from the page background.

Full width

Inset ​

A subtle variant with a slightly tinted background and no visible border or elevated panel shadow: blends naturally into page content areas.

Full width

Use slot="logo" for the logo/icon and slot="header" for the app name or branding text. Use slot="footer" for user profile or secondary actions. When collapsed, a supplied logo remains centered and the toggle stays on the panel edge. Without a logo, the toggle occupies the header itself.

Full width

Disabled Items ​

Set disabled on a ore-sidebar-item to prevent interaction. Avoid using disabled as a teaching mechanism: if an item is permanently unavailable, remove it from the sidebar instead.

Full width

When linking to external resources, use target and rel attributes on ore-sidebar-item.

html
<ore-sidebar-item href="https://example.com" target="_blank" rel="noopener noreferrer">
  <ore-icon slot="icon" name="globe" size="18"></ore-icon>
  External Docs
</ore-sidebar-item>

Imperative API ​

Collapse methods are exposed on the element instance.

js
const sidebar = document.querySelector('ore-sidebar');

sidebar.setCollapsed(true); // collapse to icon-only
sidebar.setCollapsed(false); // expand to full width
sidebar.toggle(); // toggle between states

// bottom-nav mode drawer controls
sidebar.openDrawer();
sidebar.closeDrawer();
sidebar.toggleDrawer();

Events ​

js
const sidebar = document.querySelector('ore-sidebar');

sidebar.addEventListener('collapsed-change', (e) => {
  console.log('Collapsed:', e.detail.collapsed, 'source:', e.detail.source);
});

sidebar.addEventListener('drawer-change', (e) => {
  console.log('Drawer open:', e.detail.open, 'source:', e.detail.source);
});

const group = document.querySelector('ore-sidebar-group[collapsible]');

group.addEventListener('open-change', (e) => {
  console.log('Group open:', e.detail.open);
});

Recipes ​

Section dividers ​

Drop an ore-separator between groups for a plain rule instead of a labelled heading:

html
<ore-sidebar label="App navigation">
  <ore-sidebar-group label="Workspace">…</ore-sidebar-group>
  <ore-separator></ore-separator>
  <ore-sidebar-group label="Account">…</ore-sidebar-group>
</ore-sidebar>

The footer slot fits a compact card: upgrade CTAs, usage progress, or a scan-to-install QR. Keep the card narrow: it lives inside the sidebar's width.

html
<ore-sidebar label="App navigation">
  <ore-sidebar-group label="Workspace">…</ore-sidebar-group>
  <ore-card slot="footer" padding="sm" variant="outlined">
    <p style="font-weight: var(--font-semibold);">Try Pro</p>
    <p style="font-size: var(--text-sm); color: var(--text-color-secondary);">Unlimited boards and guests.</p>
    <ore-progress value="62" aria-label="Boards used"></ore-progress>
    <ore-button variant="primary" size="sm" fullwidth>Upgrade</ore-button>
  </ore-card>
</ore-sidebar>

Scan-to-install pairs nicely with ore-qr-code:

html
<ore-qr-code
  slot="footer"
  value="https://example.test/install"
  size="112"
  error-correction="H"
  image="/favicon.svg"
  variant="card"></ore-qr-code>

CSS Customization ​

Global Variables ​

Override these CSS custom properties in your stylesheet to restyle the sidebar globally:

css
ore-sidebar {
  --sidebar-width: 18rem; /* expanded width */
  --sidebar-collapsed-width: 4rem; /* collapsed width */
  --sidebar-bg: var(--color-canvas); /* sidebar background */
  --sidebar-border-color: var(--color-divider);
}

ore-sidebar-item {
  --sidebar-item-color: var(--color-contrast-700);
  --sidebar-item-hover-bg: var(--color-contrast-100);
  --sidebar-item-hover-color: var(--color-contrast-900);
  --sidebar-item-active-bg: color-mix(in oklch, var(--color-primary) 12%, transparent);
  --sidebar-item-active-color: var(--color-primary);
}

API Reference ​

ore-sidebar Attributes

AttributeTypeDefaultDescription
collapsedbooleanN/AControlled collapsed state
default-collapsedbooleanfalseInitial collapsed state in uncontrolled mode
collapsiblebooleanfalseShows the collapse/expand toggle button in the header
responsivestringN/AMedia query that enables compact (collapsed) sidebar mode
bottom-nav-atstringN/AMedia query that switches to mobile bottom-nav + drawer mode
container-breakpointsbooleanfalseEvaluates parseable max-width breakpoints against the sidebar container width instead of the viewport
backdropstringN/ADrawer backdrop style: 'opaque' | 'blur' | 'transparent' (unset = click-to-close, no dim)
close-on-selectbooleantrueCloses the drawer after primary item activation
collapse-labelstring'Collapse sidebar'Accessible label for the collapse control
expand-labelstring'Expand sidebar'Accessible label for the expand control
drawerbooleanfalseDrawer-only mode: the sidebar exists solely as the overlay drawer
drawer-close-labelstring'Close sidebar'Accessible label for the drawer close button
variantstringN/AVisual variant: 'floating' | 'inset'
labelstring'Sidebar navigation'aria-label for the <nav> landmark

ore-sidebar Slots

SlotDescription
logoLogo or icon, always visible at the top
headerApp name or branding text, hidden when collapsed
(default)ore-sidebar-group or ore-sidebar-item elements
footerUser info, theme toggles, or secondary actions

ore-sidebar Events

EventDetailDescription
collapsed-change{ collapsed: boolean; source: 'toggle' | 'responsive' | 'api' }Fired when a collapse state change is requested
drawer-change{ open: boolean; source: 'toggle' | 'responsive' | 'api' }Fired when the drawer open state changes

ore-sidebar Methods

MethodDescription
setCollapsed(next)Set collapsed state
toggle()Toggle between collapsed / expanded
openDrawer()Open the drawer
closeDrawer()Close the drawer
toggleDrawer()Toggle the drawer

ore-sidebar CSS Custom Properties

PropertyDescriptionDefault
--sidebar-widthExpanded width16rem
--sidebar-collapsed-widthCollapsed (icon-only) width3.5rem
--sidebar-bgSidebar background colorcanvas
--sidebar-border-colorBorder / divider colorcontrast
--sidebar-header-heightHeader height in both states4rem
--sidebar-header-paddingHeader padding in both states0.75rem
--sidebar-z-indexSidebar stacking level1
--sidebar-toggle-offsetToggle offset from the top1rem
--sidebar-toggle-bgToggle backgroundpanel
--sidebar-toggle-colorToggle icon colorcontrast
--sidebar-toggle-border-colorToggle border colordivider
--sidebar-toggle-hover-bgToggle hover backgroundcontrast
--sidebar-toggle-hover-colorToggle hover icon colorcontrast
--sidebar-drawer-widthOpen drawer panel widthmin(--sidebar-width, 85vw)
--sidebar-drawer-backdrop-bgDrawer backdrop colortransparent (--overlay-veil in the dimming modes)
--sidebar-drawer-shadowShadow on the open drawer panel--shadow-xl
--sidebar-bottom-nav-heightBottom bar height3.75rem

ore-sidebar Parts

PartDescription
navThe navigation panel (inline and drawer)
headerHeader container (logo, branding, controls)
contentScrollable navigation content
footerFooter container
toggle-btnCollapse/expand toggle
drawer-close-btnClose button shown while the drawer is open
drawer-backdropBackdrop behind the open drawer (click closes it; dims only with backdrop)
swipe-handleGrabber nub that drag-closes the open drawer
bottom-barMobile bottom tab bar

ore-sidebar-group Attributes

AttributeTypeDefaultDescription
labelstring''Visible group label text
collapsiblebooleanfalseAdds a toggle button to collapse/expand the group's items
default-openbooleantrueInitial open state for uncontrolled collapsible groups
openbooleanN/AControlled group open state

ore-sidebar-group Slots

SlotDescription
iconOptional icon displayed in the group header
(default)ore-sidebar-item elements
endTrailing header content: badge, count, shortcut, etc.

ore-sidebar-group Events

EventDetailDescription
open-change{ open: boolean }Fired when an uncontrolled collapsible group opens or closes, including auto-expansion for an active item

ore-sidebar-item Attributes

AttributeTypeDefaultDescription
hrefstringN/AURL: renders an <a> when set, otherwise a <button>
activebooleanfalseMarks the item as the current page (aria-current="page")
bottom-navbooleanfalsePromotes the item into an explicit mobile bottom-nav set
bottom-nav-labelstringN/AOverrides the item text in its promoted mobile tab
disabledbooleanfalseDisables the item and forces button rendering
relstringN/Arel attribute on the inner <a> (link items only)
targetstringN/Atarget attribute on the inner <a> (link items only)

ore-sidebar-item Slots

SlotDescription
iconLeading icon (hidden from assistive tech)
(default)Item label text
endTrailing content: badge, shortcut key, chevron, etc.

ore-sidebar-item Parts

PartDescription
itemThe inner <a> or <button> element
item-iconThe icon slot wrapper
item-labelThe label text wrapper
item-endThe trailing content wrapper
item-revealCollapsed-mode label bubble

ore-sidebar-item CSS Custom Properties

PropertyDescription
--sidebar-item-colorDefault text color
--sidebar-item-hover-bgBackground on hover
--sidebar-item-hover-colorText color on hover
--sidebar-item-active-bgBackground when active
--sidebar-item-active-colorText color when active
--sidebar-item-reveal-bgLabel bubble background
--sidebar-item-reveal-colorLabel bubble text color
--sidebar-item-reveal-radiusLabel bubble corner radius
--sidebar-item-reveal-shadowLabel bubble shadow

Accessibility ​

The sidebar follows WAI-ARIA navigation patterns and WCAG 2.2 guidelines.

The ore-sidebar element renders a <nav> landmark with an aria-label. When a page has multiple navigation regions, ensure each has a unique descriptive label:

html
<ore-sidebar label="Main navigation">…</ore-sidebar> <ore-sidebar label="Documentation sidebar">…</ore-sidebar>

ore-sidebar-item sets aria-current="page" on the inner <a> or <button> when active is applied. Screen readers announce the item as the current location. Set active on the item matching the current URL on every page load, and avoid setting it on more than one item simultaneously.

When the sidebar is collapsed to icon-only mode, the toggle button updates aria-label and aria-expanded to reflect the current state, and each item reveals its hidden label in a bubble on hover and keyboard focus, so icon-only navigation stays legible without assistive tech. Navigation within the sidebar uses native DOM focus order: no roving tabindex: keeping behaviour predictable and compatible with all screen readers.

Keyboard Navigation ​

KeyBehavior
TabMoves focus to the next focusable item in DOM order
EnterActivates a focused item or toggles a collapsible header
SpaceSame as Enter on collapsible group headers
EscapeCloses the open drawer and returns focus to the opener

While the drawer is open, the rest of the page is inert: Tab cannot leave the drawer, and focus is pulled back to the panel if it escapes.