Vertical Navigation

An alternative patterns that displays navigation items in a vertical menu.

install	yarn add @clayui/nav
version
use	`import {ClayVerticalNav} from '@clayui/nav';`

Table of Contents

Example
Custom Links
Custom Trigger
API Reference

Example

import {Provider} from '@clayui/core';
import {ClayVerticalNav} from '@clayui/nav';
import React from 'react';

export default function App() {
  return (
    <Provider spritemap="/icons.svg">
      <div className="p-4">
        <ClayVerticalNav
          aria-label="vertical navbar"
          active="6"
          defaultExpandedKeys={new Set(['5'])}
          items={[
            {
              id: '1',
              items: [
                {
                  id: '2',
                  href: '#nested1',
                  label: 'Nested1',
                },
              ],
              label: 'Home',
            },
            {
              id: '3',
              href: '#2',
              label: 'About',
            },
            {
              id: '4',
              href: '#3',
              label: 'Contact',
            },
            {
              id: '5',
              items: [
                {
                  id: '6',
                  href: '#5',
                  label: 'Five',
                },
                {
                  id: '7',
                  href: '#6',
                  label: 'Six',
                },
              ],
              label: 'Projects',
            },
            {
              id: '8',
              href: '#7',
              label: 'Seven',
            },
          ]}
          large={false}
        >
          {(item) => (
            <ClayVerticalNav.Item
              href={item.href}
              items={item.items}
              key={item.id}
            >
              {item.label}
            </ClayVerticalNav.Item>
          )}
        </ClayVerticalNav>
      </div>
    </Provider>
  );
}

Custom Links

The markup between the <ClayVerticalNav.Item> tag will render inside the nav-link. In the example below, we are outputting the lock icon next to the label only for non collapsible items.

import {Provider} from '@clayui/core';
import {ClayVerticalNav} from '@clayui/nav';
import Icon from '@clayui/icon';
import React from 'react';

const noIcons = ['1', '5'];

export default function App() {
  return (
    <Provider spritemap="/icons.svg">
      <div className="p-4">
        <ClayVerticalNav
          aria-label="vertical navbar"
          active="6"
          defaultExpandedKeys={new Set(['5'])}
          items={[
            {
              id: '1',
              items: [
                {
                  id: '2',
                  href: '#nested1',
                  label: 'Nested1',
                },
              ],
              label: 'Home',
            },
            {
              id: '3',
              href: '#2',
              label: 'About',
            },
            {
              id: '4',
              href: '#3',
              label: 'Contact',
            },
            {
              id: '5',
              items: [
                {
                  id: '6',
                  href: '#5',
                  label: 'Five',
                },
                {
                  id: '7',
                  href: '#6',
                  label: 'Six',
                },
              ],
              label: 'Projects',
            },
            {
              id: '8',
              href: '#7',
              label: 'Seven',
            },
          ]}
          large={false}
        >
          {(item) => (
            <ClayVerticalNav.Item
              href={item.href}
              items={item.items}
              key={item.id}
            >
              {item.label}
              {!noIcons.includes(item.id) && (
                <span class="inline-item inline-item-after">
                  <Icon symbol="lock" />
                </span>
              )}
            </ClayVerticalNav.Item>
          )}
        </ClayVerticalNav>
      </div>
    </Provider>
  );
}

Custom Trigger

In its mobile version, Vertical Navigation adds a trigger that is responsible for opening the menu, in some cases you may want to customize this trigger, for this use the <ClayVerticalNav.Trigger /> component.

Snippet

<ClayVerticalNav
  aria-label="vertical navbar"
  trigger={(props) => (
    <ClayVerticalNav.Trigger {...props}>
      <ClayIcon
        focusable="false"
        role="presentation"
        spritemap={spritemap}
        symbol="ellipsis-v"
      />
    </ClayVerticalNav.Trigger>
  )}
/>

Your custom trigger receives the children property with the default content, for cases when you just want to change the Trigger Button and not its content.

Snippet

<ClayVerticalNav
  aria-label="vertical navbar"
  trigger={({onClick}) => (
    <button className="btn btn-secondary" onClick={onClick}>
      <ClayIcon
        focusable="false"
        role="presentation"
        spritemap={spritemap}
        symbol="ellipsis-v"
      />
    </button>
  )}
/>

API Reference

ClayVerticalNav

typeof ClayVerticalNav

Parameters

Properties

itemAriaCurrent

boolean | undefined

Flag to define if the item represents the current page. Disable this attribute only if there are multiple navigations on the page.

activation

"manual" | "automatic" | undefined

Flag to indicate the navigation behavior in the menu.

manual - it will just move the focus and menu activation is done just by pressing space or enter.
automatic - moves the focus to the menuitem and activates the menu.

Deprecated

activeLabel

string | undefined

Label of item that is currently active.

displayType

DisplayType | undefined

Determines the Vertical Nav variant to use.

decorated

boolean | undefined

Flag to activate the Decorator variation.

triggerLabel

string | undefined= "Menu"

Label of the button that appears on smaller resolutions to open the vertical navigation.

items *

Array<IItemWithItems>

List of items.

large

boolean | undefined

Flag to indicate if menubar-vertical-expand-lg class is applied.

trigger

(({ children, className, ...otherProps }: import("/Users/matuzalemteles/projects/clay/packages/clay-button/lib/Button").ButtonProps) => JSX.Element) | undefined

Custom component that will be displayed on mobile resolutions that toggles the visibility of the navigation.

spritemap

string | undefined

Path to the spritemap that Icon should use when referencing symbols.

active

React.Key | undefined

Flag to define which item has the active state/current page.

aria-label

string | undefined

Flag to define aria-label.

children

React.ReactNode | ((item: string | Record<string, any>, index?: number) => React.ReactElement)

The component contents.

defaultExpandedKeys

Set<React.Key> | undefined

Property to set the initial value of expandedKeys (uncontrolled).

expandedKeys

Set<React.Key> | undefined

The currently expanded keys in the collection (controlled).

onExpandedChange

InternalDispatch<Set<React.Key>> | undefined

A callback that is called when items are expanded or collapsed (controlled).

Returns

Element

Item

typeof Item

Parameters

Properties

Deprecated

active

boolean | undefined

Flag to indicate if item is active.

children

React.ReactNode

The contents of the component.

href

string | undefined

Link href for item.

items

Array<T> | undefined

Property to inform the dynamic data of the tree.

menubarAction

{ ariaLabel: string; title: string; } | undefined

Properties to pass to the menubar action

Returns

Element

Trigger

({ children, className, ...otherProps }: ButtonProps) => JSX.Element

Parameters

ButtonProps

Returns

Element

Edit this page on GitHub

Contributors

Matuzalém Teles, Bryce Osterhaus, Krešimir Čoko, Ilza Medeiros, Patrick Yeo, Diego Nascimento

Last edited May 11, 2025 at 5:57:01 PM

Table of Contents

Example
Custom Links
Custom Trigger
API Reference