ComponentUpdated in v15

Sidebar

Navigation drawn from data: pages and groups, three levels deep.

Installation

Import the class, and @use the entry point in your global styles: without it the component renders unstyled.

import { Component } from '@angular/core';
import { WrSidebar } from 'ngwr/sidebar';

@Component({ imports: [WrSidebar] })
export class MyComponent {}

Basic usage

Pass [entries]: pages and groups. Every group above the current route opens.

<wr-sidebar [entries]="entries" />

To drop the inner padding, set --wr-sidebar-padding: 0 on .wr-sidebar, not on its container.

Subtitle, badge and count

Any row can take a one-line subtitle, a word badge under the title and a count at the end. Give a group a url to make it a page too.

protected readonly entries: WrSidebarEntry[] = [
  { title: 'Introduction', icon: 'book', url: ['/intro'] },
  {
    title: 'Components',
    count: 4,
    countLabel: '4 pages', // what a screen reader hears
    children: [
      {
        title: 'Graph',
        subtitle: 'Nodes and edges',
        badge: { text: 'New', tone: 'primary' }, // 'neutral' | 'primary' | 'danger'
        url: ['/components/graph'],
      },
      {
        title: 'Navigation',
        url: ['/components/navigation'], // also a page: the arrow opens it
        children: [{ title: 'Sidebar', url: ['/components/sidebar'] }],
      },
    ],
  },
];

Which route counts as active

Pages match by URL prefix, so give ['/'] activeOptions: { exact: true }, or it is the current page everywhere.

protected readonly entries: WrSidebarEntry[] = [
  // Without exact, '/' matches every URL
  { title: 'Home', url: ['/'], activeOptions: { exact: true } },
  { title: 'Orders', url: ['/orders'] }, // stays active on /orders/42
];

API

NameDescriptionTypeDefault
entriesPages and groups, in order. Groups nest three levels deep.readonly WrSidebarEntry[][]
ariaLabelName of the navigation landmark. Falls back to sidebar.label.string | nullnull
defaultGroupIconIcon for a group whose icon is omitted. null draws none.string | nullnull
defaultItemIconIcon for a page whose icon is omitted. null draws none.string | nullnull
autoExpandOpen every group above the current route.booleantrue
autoCollapseClose the groups the last navigation opened when the next one leaves them.booleanfalse
WrSidebarRow{ title, subtitle?, icon?, badge?, count?, countLabel? }: what every row shows.interface—
WrSidebarItemWrSidebarRow plus { url, disabled?, activeOptions? }: a page.interface—
WrSidebarGroupWrSidebarRow plus { children, url?, defaultOpen? }: a group, and a page too with url.interface—
WrSidebarBadge{ text, tone? }, where tone is 'neutral', 'primary' or 'danger'.interface—
WrSidebarActiveOptions{ exact: boolean } or any subset of the router's own match options.type—

CSS variables

Set these on the component's selector or a wrapper, not on :root: the defaults are declared on ngwr/sidebar's own element.

VariableDefaultDeclared on
--wr-sidebar-badge-font-size0.5625rem.wr-sidebar
--wr-sidebar-badge-font-weightvar(--wr-font-weight-semibold).wr-sidebar
--wr-sidebar-badge-line-height0.75rem.wr-sidebar
--wr-sidebar-badge-padding-xvar(--wr-space-xs).wr-sidebar
--wr-sidebar-badge-radius0.25rem.wr-sidebar
--wr-sidebar-chevroncolor-mix(in srgb, var(--wr-color-on-surface-muted) 70%, transparent).wr-sidebar
--wr-sidebar-chevron-size0.875rem.wr-sidebar +1 variant override
--wr-sidebar-font-familyvar(--wr-font-family-base).wr-sidebar
--wr-sidebar-gap0.125rem.wr-sidebar
--wr-sidebar-group-gap0.375rem.wr-sidebar
--wr-sidebar-guidevar(--wr-border-base).wr-sidebar
--wr-sidebar-guide-gapvar(--wr-space-sm).wr-sidebar
--wr-sidebar-guide-width1px.wr-sidebar
--wr-sidebar-icon-gapvar(--wr-space-sm).wr-sidebar
--wr-sidebar-icon-size1rem.wr-sidebar
--wr-sidebar-meta-gap0.375rem.wr-sidebar
--wr-sidebar-paddingvar(--wr-space-sm).wr-sidebar
--wr-sidebar-row-font-sizevar(--wr-text-sm).wr-sidebar
--wr-sidebar-row-height2rem.wr-sidebar +1 variant override
--wr-sidebar-row-line-heightvar(--wr-text-sm-leading).wr-sidebar
--wr-sidebar-row-padding-xvar(--wr-space-sm).wr-sidebar
--wr-sidebar-row-padding-y0.375rem.wr-sidebar +1 variant override
--wr-sidebar-row-radiusvar(--wr-border-radius-sm).wr-sidebar
--wr-sidebar-subtitle-font-sizevar(--wr-text-xs).wr-sidebar
--wr-sidebar-subtitle-line-heightvar(--wr-text-xs-leading).wr-sidebar

Dependencies

@angular/router@angular/router(optional peer)
Built onIcon

See also