Docs

Docs

Side Navigation

Side Navigation provides a vertical list of navigation links with support for collapsible, nested sections.

Side Navigation provides a vertical list of navigation links with support for collapsible, nested sections.

Important
Preview Feature

This is a preview release of the Side Navigation component. Its behavior, API, and look and feel might change. To use this component, it must be explicitly enabled with a feature flag. See the Feature Flag section to learn how to do this.

Note
Navigation Disabled in Examples

For technical reasons, actual navigation is disabled in the examples on this page.

Open in a
new tab
<SideNav style={{ width: '100%' }} id="sideNav" ref={sideNavRef}>
  <SideNavItem path="/dashboard">
    <Icon icon="vaadin:dashboard" slot="prefix" />
    Dashboard
  </SideNavItem>
  <SideNavItem path="/inbox">
    <Icon icon="vaadin:envelope" slot="prefix" />
    Inbox
  </SideNavItem>
  <SideNavItem path="/calendar">
    <Icon icon="vaadin:calendar" slot="prefix" />
    Calendar
  </SideNavItem>
  <SideNavItem path="/settings">
    <Icon icon="vaadin:cog" slot="prefix" />
    Settings
  </SideNavItem>
  <SideNavItem path="https://vaadin.com">
    <Icon icon="vaadin:vaadin-h" slot="prefix" />
    Vaadin website
  </SideNavItem>
</SideNav>

The navigation item whose path matches the current URL is highlighted as active. The Side Navigation component can be used, for example, in the drawer of an App Layout.

Prefix & Suffix Elements

Navigation items have slots for prefix and suffix elements. The prefix slot is primarily intended for icons, while the suffix slot can be used, for example, for notification badges.

Interactive prefix and suffix elements aren’t recommended since the entire item row acts as a link.

Open in a
new tab
<SideNav style={{ width: '100%' }} ref={sideNavRef}>
  <SideNavItem path="/inbox">
    <Icon icon="vaadin:envelope" slot="prefix" />
    Inbox
    <span
      {...{ theme: 'badge contrast pill' }}
      slot="suffix"
      aria-label="12 unread messages"
    >
      12
    </span>
  </SideNavItem>
  <SideNavItem path="/calendar">
    <Icon icon="vaadin:calendar" slot="prefix" />
    Calendar
    <Icon
      icon="vaadin:bell"
      theme="badge error pill"
      style={{ padding: 'var(--lumo-space-xs)' }}
      aria-label="Upcoming appointment"
      slot="suffix"
    ></Icon>
  </SideNavItem>
</SideNav>

Hierarchy

Navigation items can contain sub-items, which are collapsed by default. There’s no technical limitation on the number of nesting levels, but a maximum of three levels is recommended for better usability.

Parent items can be links. Clicking them expands their sub-items in addition to navigating. Non-link parent items can be achieved by omitting the target path.

Open in a
new tab
<SideNav style={{ width: '100%' }} id="sideNav" ref={sideNavRef}>
  <SideNavItem path="/messages">
    <Icon icon="vaadin:envelope" slot="prefix" />
    Messages
    <SideNavItem path="/inbox" slot="children">
      <Icon icon="vaadin:inbox" slot="prefix" />
      Inbox
    </SideNavItem>
    <SideNavItem path="/sent" slot="children">
      <Icon icon="vaadin:paperplane" slot="prefix" />
      Sent
    </SideNavItem>
    <SideNavItem path="/trash" slot="children">
      <Icon icon="vaadin:trash" slot="prefix" />
      Trash
    </SideNavItem>
  </SideNavItem>
  <SideNavItem>
    <Icon icon="vaadin:cog" slot="prefix" />
    Admin
    <SideNavItem path="/users" slot="children">
      <Icon icon="vaadin:group" slot="prefix" />
      Users
    </SideNavItem>
    <SideNavItem path="/permissions" slot="children">
      <Icon icon="vaadin:key" slot="prefix" />
      Permissions
    </SideNavItem>
  </SideNavItem>
</SideNav>

Labelled Collapsible List

A label can be applied to the top of the navigation list. This can be useful for cases with multiple adjacent Side Navigation lists. A labeled Side Navigation list can be made collapsible.

Open in a
new tab
<VerticalLayout theme="spacing">
  <SideNav style={{ width: '100%' }} ref={sideNavRef}>
    <span slot="label">Messages</span>
    <SideNavItem path="/inbox">
      <Icon icon="vaadin:inbox" slot="prefix"></Icon>
      Inbox
    </SideNavItem>
    <SideNavItem path="/sent">
      <Icon icon="vaadin:paperplane" slot="prefix"></Icon>
      Sent
    </SideNavItem>
    <SideNavItem path="/trash">
      <Icon icon="vaadin:trash" slot="prefix"></Icon>
      Trash
    </SideNavItem>
  </SideNav>
  <SideNav style={{ width: '100%' }} collapsible ref={secondSideNavRef}>
    <span slot="label">Admin</span>
    <SideNavItem path="/users">
      <Icon icon="vaadin:group" slot="prefix"></Icon>
      Users
    </SideNavItem>
    <SideNavItem path="/permissions">
      <Icon icon="vaadin:key" slot="prefix"></Icon>
      Permissions
    </SideNavItem>
  </SideNav>
</VerticalLayout>

Scrolling

The Side Navigation component doesn’t contain a scroll area. Instead, it can be made scrollable by wrapping it inside a Scroller.

Keyboard Usage

Shortcut Function

Tab

Navigation between list items.

Tab

Navigation between link and expand/collapse button.

Enter / Space

Toggles expand/collapse.

Enter

Trigger link.

Styling Individual Items

Individual navigation items can be styled by applying a CSS class name to them.

Open in a
new tab
<SideNav style={{ width: '100%' }} ref={sideNavRef}>
  <SideNavItem path="/dashboard">
    <Icon icon="vaadin:dashboard" slot="prefix" />
    Dashboard
  </SideNavItem>
  <SideNavItem path="/inbox">
    <Icon icon="vaadin:envelope" slot="prefix" />
    Inbox
  </SideNavItem>
  <SideNavItem path="https://vaadin.com" className="external">
    <Icon icon="vaadin:vaadin-h" slot="prefix" />
    Vaadin website
  </SideNavItem>
</SideNav>

Feature Flag

In order to use the Side Navigation component, it must be explicitly enabled with a feature flag. To do this, there are two methods: use Vaadin Developer Tools; or add a Feature Flags properties file.

To use Developer Tools, click its icon button in your running application. Then open the Feature Flags tab. Enable the SideNav component feature and restart the application.

To add a Feature Flags properties file, first create a src/main/resources/vaadin-featureflags.properties file in your application folder. Add to it com.vaadin.experimental.sideNavComponent=true. Then restart the application.