Light Dark System

Secondary Navigation

<cw-secondary-navigation> | CwSecondaryNavigation
Since 1.3 experimental

Second-level site navigation for linking pages related to the current one, beneath a <cw-primary-navigation>. A flat, horizontal strip of links — unlike primary navigation, it has no disclosure/dropdown items; overflow is handled with scroll buttons instead.

Add one <cw-secondary-navigation-item> per related page. Unlike Primary Navigation, items are always flat links — there’s no dropdown/disclosure mode. When items overflow the available width, scroll buttons appear automatically.

Overview Installation Theming Frameworks 
<cw-secondary-navigation>
  <cw-secondary-navigation-item href="/docs/overview" current>Overview</cw-secondary-navigation-item>
  <cw-secondary-navigation-item href="/docs/installation">Installation</cw-secondary-navigation-item>
  <cw-secondary-navigation-item href="/docs/theming">Theming</cw-secondary-navigation-item>
  <cw-secondary-navigation-item href="/docs/frameworks">Frameworks</cw-secondary-navigation-item>
</cw-secondary-navigation>

import { CwSecondaryNavigation, CwSecondaryNavigationItem } from '@cordwainer/cw-elements/dist/react';

const App = () => (
  <CwSecondaryNavigation>
    <CwSecondaryNavigationItem href="/docs/overview" current>
      Overview
    </CwSecondaryNavigationItem>
    <CwSecondaryNavigationItem href="/docs/installation">Installation</CwSecondaryNavigationItem>
    <CwSecondaryNavigationItem href="/docs/theming">Theming</CwSecondaryNavigationItem>
    <CwSecondaryNavigationItem href="/docs/frameworks">Frameworks</CwSecondaryNavigationItem>
  </CwSecondaryNavigation>
);

Examples

Current Page

Set the current attribute on the item that represents the page the user is on. The component has no router or URL awareness — set it based on your own routing state.

Overview Installation 
<cw-secondary-navigation>
  <cw-secondary-navigation-item href="/docs/overview">Overview</cw-secondary-navigation-item>
  <cw-secondary-navigation-item href="/docs/installation" current>Installation</cw-secondary-navigation-item>
</cw-secondary-navigation>

import { CwSecondaryNavigation, CwSecondaryNavigationItem } from '@cordwainer/cw-elements/dist/react';

const App = () => (
  <CwSecondaryNavigation>
    <CwSecondaryNavigationItem href="/docs/overview">Overview</CwSecondaryNavigationItem>
    <CwSecondaryNavigationItem href="/docs/installation" current>
      Installation
    </CwSecondaryNavigationItem>
  </CwSecondaryNavigation>
);

Overflow

When items don’t fit the available width, scroll buttons appear at each end. Resize this preview’s frame to see them engage.

First page Second page Third page Fourth page Fifth page Sixth page 
<cw-secondary-navigation class="secondary-navigation-demo-narrow">
  <cw-secondary-navigation-item href="/a">First page</cw-secondary-navigation-item>
  <cw-secondary-navigation-item href="/b">Second page</cw-secondary-navigation-item>
  <cw-secondary-navigation-item href="/c">Third page</cw-secondary-navigation-item>
  <cw-secondary-navigation-item href="/d">Fourth page</cw-secondary-navigation-item>
  <cw-secondary-navigation-item href="/e">Fifth page</cw-secondary-navigation-item>
  <cw-secondary-navigation-item href="/f">Sixth page</cw-secondary-navigation-item>
</cw-secondary-navigation>

<style>
  .secondary-navigation-demo-narrow {
    max-width: 300px;
  }
</style>

import { CwSecondaryNavigation, CwSecondaryNavigationItem } from '@cordwainer/cw-elements/dist/react';

const css = `
  .secondary-navigation-demo-narrow {
    max-width: 300px;
  }
`;

const App = () => (
  <>
    <CwSecondaryNavigation className="secondary-navigation-demo-narrow">
      <CwSecondaryNavigationItem href="/a">First page</CwSecondaryNavigationItem>
      <CwSecondaryNavigationItem href="/b">Second page</CwSecondaryNavigationItem>
      <CwSecondaryNavigationItem href="/c">Third page</CwSecondaryNavigationItem>
      <CwSecondaryNavigationItem href="/d">Fourth page</CwSecondaryNavigationItem>
      <CwSecondaryNavigationItem href="/e">Fifth page</CwSecondaryNavigationItem>
      <CwSecondaryNavigationItem href="/f">Sixth page</CwSecondaryNavigationItem>
    </CwSecondaryNavigation>

    <style>{css}</style>
  </>
);

Pass no-scroll-controls to disable the buttons and let the strip scroll natively (e.g. via touch) instead.

Custom Label

The <nav> landmark’s accessible name defaults to a localized “Secondary navigation”. Pass label to override it — useful for distinguishing it from other navigation landmarks on the same page, including a <cw-primary-navigation> above it.

Overview Installation 
<cw-secondary-navigation label="Docs sections">
  <cw-secondary-navigation-item href="/docs/overview">Overview</cw-secondary-navigation-item>
  <cw-secondary-navigation-item href="/docs/installation">Installation</cw-secondary-navigation-item>
</cw-secondary-navigation>

import { CwSecondaryNavigation, CwSecondaryNavigationItem } from '@cordwainer/cw-elements/dist/react';

const App = () => (
  <CwSecondaryNavigation label="Docs sections">
    <CwSecondaryNavigationItem href="/docs/overview">Overview</CwSecondaryNavigationItem>
    <CwSecondaryNavigationItem href="/docs/installation">Installation</CwSecondaryNavigationItem>
  </CwSecondaryNavigation>
);

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script Import Bundler React

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/@cordwainer/cw-elements@1.5.2/cdn/components/secondary-navigation/secondary-navigation.js"></script>

To import this component from the CDN using a JavaScript import: 

import 'https://cdn.jsdelivr.net/npm/@cordwainer/cw-elements@1.5.2/cdn/components/secondary-navigation/secondary-navigation.js';

To import this component using a bundler:

import '@cordwainer/cw-elements/dist/components/secondary-navigation/secondary-navigation.js';

To import this component as a React component:

import CwSecondaryNavigation from '@cordwainer/cw-elements/dist/react/secondary-navigation';

Slots

Name Description
(default) One or more <cw-secondary-navigation-item> elements.

Learn more about using slots.

Properties

Name Description Reflects Type Default
label The accessible label for the <nav> landmark. Defaults to a localized “Secondary navigation”. string ''
noScrollControls
no-scroll-controls 		Disables the scroll arrows that appear when items overflow. boolean false
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Parts

Name Description
base The component’s base wrapper, a <nav> landmark element.
nav The container that wraps the slotted navigation items and the scroll buttons.
scroll-button The previous/next scroll buttons that show when items overflow, an <cw-icon-button>.
scroll-button--start The starting scroll button.
scroll-button--end The ending scroll button.
scroll-button__base The scroll button’s exported base part.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

  • <cw-icon>
  • <cw-icon-button>