CSC Design System v4.0.0
VueFlavour Vue React Angular TypeScript
Flavour Vue React Angular TypeScript
PrimaryCSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
CSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
Guides Getting started Customization Data visualization Migration guide Componentsc-accordionc-alertc-autocompletec-badgec-breadcrumbc-buttonc-button-groupc-cardc-checkboxc-color-pickerc-csc-logoc-data-tablec-date-pickerc-dividerc-file-uploadc-iconc-icon-buttonc-linkc-listc-loaderc-login-buttonsc-login-cardc-mainc-menuc-messagec-modalc-navigation-buttonc-number-fieldc-otp-inputc-pagec-paginationc-popoverc-progress-barc-progress-circlec-radio-groupc-selectc-side-navigationc-sliderc-spinnerc-statusc-stepsc-switchc-tablec-tabsc-tagsc-text-fieldc-time-pickerc-toastsc-toolbarc-tooltipc-tree-select

<c-side-navigation>

The dashboard layout's left-hand menu: section titles, navigation items and their sub-items in a drawer that is pinned beside the page on desktop and slides in over it on mobile.

Usage

Titles, items and sub-items

Author the menu as a flat list of c-side-navigation-title and c-side-navigation-item elements: a title heads the items that follow it, up to the next title.

Write an item's sub-items as c-sub-navigation-item children inside it; the item slots them itself, including sub-items added later. An item with sub-items is an expandable parent with a chevron: activating it toggles its expanded state, which shows or hides the sub-items, and activating any top-level item collapses the other parents, so one stays open at a time. Set expanded on a parent to open it initially. A parent only expands and collapses — activating it does not close the mobile drawer. The sub-items of a collapsed parent leave the Tab order.

current marks the item, or sub-item, of the page shown (aria-current="page"). To mark a page under a parent, set current on the sub-item and expanded on its parent. The 3.x active still works until 5.0, meaning expanded on a parent and current elsewhere; current and expanded win when set.

<c-side-navigation>
  <c-side-navigation-title>My project</c-side-navigation-title>
  <c-side-navigation-item value="dashboard">Dashboard</c-side-navigation-item>
  <c-side-navigation-item value="projects" expanded>
    Projects
    <c-sub-navigation-item value="active" current>
      Active projects
    </c-sub-navigation-item>
    <c-sub-navigation-item value="archived">
      Archived projects
    </c-sub-navigation-item>
  </c-side-navigation-item>
</c-side-navigation>

Selecting an item

Activating an item — a click, or Enter — fires select with { value }, the item's value. Sub-items fire it too, and it bubbles, so one listener on the navigation can route every item:

<c-side-navigation @select="navigate($event.detail.value)">
  <c-side-navigation-item
    value="/dashboard"
    :current="route.path === '/dashboard'"
  >
    Dashboard
  </c-side-navigation-item>
</c-side-navigation>

The navigation does not mark the current page itself: set current on the item, or sub-item, of the page shown, from your router or the URL. The highlight then follows the page, not the click, so a navigation your router cancels leaves it where it was.

Inside c-main

Slot it as a direct child of c-main and the dashboard layout places and pins it: the drawer sits beneath the toolbar — or at the top edge once a static toolbar has scrolled away — is sized to the pinned height, and scrolls a long menu on its own. No host class is needed; the 3.x autoheight class is ignored there.

Bottom slot

Trailing content — a sign-out button, a help link — goes in the bottom slot. It stays at the drawer's bottom edge while the items scroll above it: the viewport's bottom edge on desktop, the panel's in the mobile drawer. It is reached without scrolling the menu and is not a menu item.

Mobile

Set mobile to render the drawer as a panel that slides in from the right over a backdrop. open opens and closes it, and a c-navigation-button anywhere on the page toggles it. Whenever the user opens or closes it — the navigation button, the close button, the backdrop, or activating an item, which closes it — the drawer fires change:open with the new state. Without mobile the drawer is always shown: a c-navigation-button and activating an item leave it as it is, and fire nothing.

The open mobile drawer is a modal dialog named "Menu": focus moves to its close button, the page behind it is inert and stops scrolling, and Escape closes it, as the close button and the backdrop do. Closing returns focus to where it was, usually the navigation button.

Standalone

Outside c-main the drawer is an ordinary block that grows with its items. The autoheight host class sizes it to the viewport minus the toolbar height and lets its item list scroll, for a shell that pins the drawer itself.

Accessibility

The navigation is a <nav> landmark; an aria-label on the element names it, which helps beside other navigation on the page. Items are what they do: an item or sub-item with href is a link, one without is a button, and a parent is a disclosure button that reports its sub-items as expanded or collapsed. Tab moves through the items; there is no arrow-key model. The current page carries aria-current="page", and section titles are headings (level 2). The close button's name and the drawer's "Menu" are fixed English strings.

Customization

Structural styling via ::part(root) (the drawer) and ::part(nav) (the scrolling item list). The surface is the nav-surface token role; override the tokens to re-theme.

Examples

Basic
Vue React Angular TypeScript
<template>
  <div>
    <c-side-navigation>
      <c-side-navigation-title>My project</c-side-navigation-title>

      <c-side-navigation-item
        :current="current === 'dashboard'"
        @select="current = 'dashboard'"
      >
        <c-icon :path="mdiViewDashboardOutline" />
        Dashboard
      </c-side-navigation-item>

      <c-side-navigation-item expanded>
        <c-icon :path="mdiFolderOutline" />
        Projects

        <c-sub-navigation-item
          :current="current === 'active'"
          @select="current = 'active'"
        >
          Active projects
        </c-sub-navigation-item>

        <c-sub-navigation-item
          :current="current === 'archived'"
          @select="current = 'archived'"
        >
          Archived projects
        </c-sub-navigation-item>
      </c-side-navigation-item>

      <c-side-navigation-item href="https://csc.fi" target="_blank">
        <c-icon :path="mdiOpenInNew" />
        Service description
      </c-side-navigation-item>
    </c-side-navigation>
  </div>
</template>

<script setup lang="ts">
import {
  mdiFolderOutline,
  mdiOpenInNew,
  mdiViewDashboardOutline,
} from '@mdi/js';
import { ref } from 'vue';

const current = ref('active');
</script>
Basic · c-side-navigation-item
Vue React Angular TypeScript
<template>
  <div>
    <c-side-navigation>
      <c-side-navigation-item
        :current="current === 'dashboard'"
        @select="current = 'dashboard'"
      >
        <c-icon :path="mdiViewDashboardOutline" />
        Dashboard
      </c-side-navigation-item>

      <c-side-navigation-item expanded>
        <c-icon :path="mdiFolderOutline" />
        Projects

        <c-sub-navigation-item
          :current="current === 'active'"
          @select="current = 'active'"
        >
          Active projects
        </c-sub-navigation-item>

        <c-sub-navigation-item
          :current="current === 'archived'"
          @select="current = 'archived'"
        >
          Archived projects
        </c-sub-navigation-item>
      </c-side-navigation-item>

      <c-side-navigation-item href="https://csc.fi" target="_blank">
        <c-icon :path="mdiOpenInNew" />
        Service description
      </c-side-navigation-item>
    </c-side-navigation>
  </div>
</template>

<script setup lang="ts">
import {
  mdiFolderOutline,
  mdiOpenInNew,
  mdiViewDashboardOutline,
} from '@mdi/js';
import { ref } from 'vue';

const current = ref('dashboard');
</script>
Basic · c-side-navigation-title
Vue React Angular TypeScript
<template>
  <div>
    <c-side-navigation>
      <c-side-navigation-title>Services</c-side-navigation-title>

      <c-side-navigation-item>
        <c-icon :path="mdiDatabaseOutline" />
        Data storage
      </c-side-navigation-item>

      <c-side-navigation-item>
        <c-icon :path="mdiServerNetwork" />
        Computing
      </c-side-navigation-item>

      <c-side-navigation-title>Support</c-side-navigation-title>

      <c-side-navigation-item>
        <c-icon :path="mdiHelpCircleOutline" />
        User guides
      </c-side-navigation-item>
    </c-side-navigation>
  </div>
</template>

<script setup lang="ts">
import {
  mdiDatabaseOutline,
  mdiHelpCircleOutline,
  mdiServerNetwork,
} from '@mdi/js';
</script>
Basic · c-sub-navigation-item
Vue React Angular TypeScript
<template>
  <div>
    <c-side-navigation>
      <c-side-navigation-item expanded>
        <c-icon :path="mdiFolderOutline" />
        Projects

        <c-sub-navigation-item
          :current="current === 'active'"
          @select="current = 'active'"
        >
          Active projects
        </c-sub-navigation-item>

        <c-sub-navigation-item
          :current="current === 'archived'"
          @select="current = 'archived'"
        >
          Archived projects
        </c-sub-navigation-item>

        <c-sub-navigation-item href="https://csc.fi" target="_blank">
          Service description
        </c-sub-navigation-item>
      </c-side-navigation-item>
    </c-side-navigation>
  </div>
</template>

<script setup lang="ts">
import { mdiFolderOutline } from '@mdi/js';
import { ref } from 'vue';

const current = ref('active');
</script>

API reference

<c-side-navigation>

The dashboard layout's left-hand menu: section titles, navigation items and their sub-items in a drawer that is pinned beside the page on desktop and slides in over it on mobile.

Properties

PropertyAttributeTypeDefaultDescription
mobilemobilebooleanfalse Render the drawer as a panel that slides in from the right over a backdrop, opened and closed by `open` or a `c-navigation-button`; while open it is a modal dialog.
openopenbooleanfalse Whether the `mobile` drawer is open. A `c-navigation-button` anywhere on the page toggles it.

Events

EventDetailDescription
change:openbooleanFired when the user opens or closes the drawer — a `c-navigation-button`, the close button, the backdrop, or activating an item — carrying the new `open`. Named `change:open`, not `update:open`: Vue's runtime silently drops `onUpdate:*` listeners on custom elements (`isModelListener`).

Slots

SlotDescription
defaultThe navigation items: titles, items and their sub-items
bottomTrailing content below the items, such as a sign-out button; it stays at the drawer's bottom edge while the items scroll

CSS parts

Style from outside with c-side-navigation::part(name) — parts are the library's only styling customization API.

PartDescription
rootThe outer drawer container: the item list above the bottom slot's region; the open mobile drawer is a modal `dialog`
navThe scrollable `<nav>` element holding the navigation items

<c-side-navigation-item>

One entry of a `c-side-navigation`: its label text, after an optional leading `c-icon`, goes in the default slot, and activating it fires `select` with its `value`; with `href` it is a real link, opened in `target`, and without one a button. Write `c-sub-navigation-item` children inside it to make it an expandable parent, shown open while `expanded`; an item without sub-items marks the page shown with `current`.

Properties

PropertyAttributeTypeDefaultDescription
currentcurrentboolean— Mark the item as the page shown (`aria-current="page"`), on an item without sub-items. Bind it from the page your router or the URL shows: the navigation never sets it.
expandedexpandedboolean— Show a parent item's sub-items. The navigation sets it as parents open and close, collapsing the other top-level parents; set it to open one initially.
hrefhrefstring'' URL that makes the item a real link; without it the item is a button.
loadingloadingbooleanfalse Cover the item with a loading overlay: a translucent scrim and a spinner.
targettargetstring'' Where the `href` opens, as on a native `<a>`: the same tab unless set — `_blank` for a new one.
valuevaluestring— Value reported in the `select` event when the item is activated
active deprecated activebooleanfalse Deprecated. Use `current` on an item without sub-items and `expanded` on a parent. On an item without sub-items, mark the current page (`aria-current="page"`); on a parent, expand its sub-items.

Events

EventDetailDescription
select{ value: string | undefined }Fired when the item is activated (click or Enter), carrying its `value`; bubbles out of the navigation, as `c-menu`'s does, so one listener on `c-side-navigation` can handle every item.

Slots

SlotDescription
defaultThe item's label content (text and an optional c-icon)

CSS parts

Style from outside with c-side-navigation-item::part(name) — parts are the library's only styling customization API.

PartDescription
rootThe outer box wrapping the header and sub-navigation, carrying the background and state styling
headerThe clickable header row (an `<a>` when `href` is set) holding the chevron and label
sub-navThe collapsible group holding the sub-items

<c-side-navigation-title>

A section title in a `c-side-navigation`: uppercase text over a divider line, placed before the items it groups. It is a heading (level 2), so screen-reader users can jump between sections, and cannot be activated.

Slots

SlotDescription
defaultThe title text of the navigation section

CSS parts

Style from outside with c-side-navigation-title::part(name) — parts are the library's only styling customization API.

PartDescription
rootThe outer wrapper around the label and the divider
headingThe uppercase section heading
divider-rootThe underline divider's root element, forwarded from the inner c-divider

<c-sub-navigation-item>

A second-level entry of a `c-side-navigation`, written inside the `c-side-navigation-item` it belongs to (no `slot` attribute needed) and shown while that parent is `expanded`. Activating it fires `select` with its `value` and closes the mobile drawer. It does not mark itself as the current page: set `current` on the sub-item of the page shown, and `expanded` on its parent.

Properties

PropertyAttributeTypeDefaultDescription
currentcurrentboolean— Mark the sub-item as the page shown (`aria-current="page"`), and set `expanded` on its parent item so the parent is open. Bind it from the page your router or the URL shows: the navigation never sets it.
hrefhrefstring'' URL that makes the sub-item a real link; without it the sub-item is a button.
loadingloadingbooleanfalse Cover the sub-item with a loading overlay: a translucent scrim and a spinner.
targettargetstring'' Where the `href` opens, as on a native `<a>`: the same tab unless set — `_blank` for a new one.
valuevaluestring— Value reported in the `select` event when the item is activated
active deprecated activebooleanfalse Deprecated. Use `current`. Mark the sub-item as the current page (`aria-current="page"`); set `active` on its parent item too, so the parent is expanded.

Events

EventDetailDescription
select{ value: string | undefined }Fired when the item is activated (click or Enter), carrying its `value`; bubbles out of the navigation, as `c-side-navigation-item`'s does.

Slots

SlotDescription
defaultThe visible content of the navigation item

CSS parts

Style from outside with c-sub-navigation-item::part(name) — parts are the library's only styling customization API.

PartDescription
rootThe focusable menu-item row carrying the hover/active styling and the leading indicator
contentWrapper around the slotted content inside the row