Skip to main content

Breadcrumbs

Breadcrumbs are navigation aids for showing where the current page sits in a hierarchy, like a product within its category. They list each parent page and can collapse long paths.

Import

import { Breadcrumbs } from '@vortexlabs/vortex';
import type { BreadcrumbsProps } from '@vortexlabs/vortex';

Other links

Storybook

Features

  • Renders a labeled navigation landmark.
  • Marks the current page with aria-current.
  • Supports chevron or slash separators and optional item icons.
  • Can collapse long paths and expand hidden items.
  • Controls how many leading and trailing items remain visible.
Reference Links
WAI-ARIA breadcrumb pattern

Usage

Add a Breadcrumbs.Item for each level. Use href for destinations and current for the page the user is viewing.

In Next.js App Router, Breadcrumbs.Item requires a client boundary. Add "use client" unless the file is already part of one.

"use client";

import { Breadcrumbs } from "@vortexlabs/vortex";

export const BreadcrumbsUsage = () => {
  return (
    <Breadcrumbs ariaLabel="Breadcrumb">
      <Breadcrumbs.Item href="/docs/introduction">Docs</Breadcrumbs.Item>
      <Breadcrumbs.Item href="/docs/all-components">Components</Breadcrumbs.Item>
      <Breadcrumbs.Item current>Breadcrumbs</Breadcrumbs.Item>
    </Breadcrumbs>
  );
};

Separators

The default separator is chevron. Set dividerType="slash" to use slashes between items.

"use client";

import { Breadcrumbs } from "@vortexlabs/vortex";

export const BreadcrumbsSeparators = () => {
  return (
    <Breadcrumbs ariaLabel="Breadcrumb with slashes" dividerType="slash">
      <Breadcrumbs.Item href="/docs/introduction">Docs</Breadcrumbs.Item>
      <Breadcrumbs.Item href="/docs/all-components">Components</Breadcrumbs.Item>
      <Breadcrumbs.Item current>Breadcrumbs</Breadcrumbs.Item>
    </Breadcrumbs>
  );
};

Icons

Use icon on an item to add an icon before its label. Keep the text label so each destination remains clear.

"use client";

import { Breadcrumbs } from "@vortexlabs/vortex";
import { Folder } from "@vortexlabs/vortex-icons";

export const BreadcrumbsIcons = () => {
  return (
    <Breadcrumbs ariaLabel="Breadcrumb with an icon">
      <Breadcrumbs.Item href="/docs/introduction" icon={<Folder />}>
        Docs
      </Breadcrumbs.Item>
      <Breadcrumbs.Item href="/docs/all-components">Components</Breadcrumbs.Item>
      <Breadcrumbs.Item current>Breadcrumbs</Breadcrumbs.Item>
    </Breadcrumbs>
  );
};

Long Labels

String and number labels truncate to 19 characters at xs and 35 at sm and above, including .... Keep labels short and distinct; screen readers receive the shortened text too.

"use client";

import { Breadcrumbs } from "@vortexlabs/vortex";

export const BreadcrumbsLongLabels = () => {
  return (
    <Breadcrumbs ariaLabel="Breadcrumb with a long label">
      <Breadcrumbs.Item href="/docs/introduction">Docs</Breadcrumbs.Item>
      <Breadcrumbs.Item current>Configuring navigation for a large workspace</Breadcrumbs.Item>
    </Breadcrumbs>
  );
};

Collapsed Paths

Set maxItems to 2 or more to collapse long paths. Provide maxItemsAriaLabel to label the button that reveals hidden items.

"use client";

import { Breadcrumbs } from "@vortexlabs/vortex";

export const BreadcrumbsCollapsed = () => {
  return (
    <Breadcrumbs
      ariaLabel="Collapsed breadcrumb"
      maxItems={3}
      maxItemsAriaLabel="Show full breadcrumb"
    >
      <Breadcrumbs.Item href="/docs/introduction">Vortex</Breadcrumbs.Item>
      <Breadcrumbs.Item href="/docs/quick-start">Docs</Breadcrumbs.Item>
      <Breadcrumbs.Item href="/docs/all-components">Components</Breadcrumbs.Item>
      <Breadcrumbs.Item href="/docs/components/link">Navigation</Breadcrumbs.Item>
      <Breadcrumbs.Item current>Breadcrumbs</Breadcrumbs.Item>
    </Breadcrumbs>
  );
};

Leading and Trailing Items

Use itemsBeforeCollapse and itemsAfterCollapse to set how many items stay visible on each side of the ellipsis. These replace maxItems; an omitted count defaults to 1.

"use client";

import { Breadcrumbs } from "@vortexlabs/vortex";

export const BreadcrumbsEdges = () => {
  return (
    <Breadcrumbs
      ariaLabel="Breadcrumb with custom collapse"
      itemsBeforeCollapse={2}
      itemsAfterCollapse={1}
      maxItemsAriaLabel="Show hidden parent pages"
    >
      <Breadcrumbs.Item href="/docs/introduction">Vortex</Breadcrumbs.Item>
      <Breadcrumbs.Item href="/docs/quick-start">Docs</Breadcrumbs.Item>
      <Breadcrumbs.Item href="/docs/all-components">Components</Breadcrumbs.Item>
      <Breadcrumbs.Item href="/docs/components/link">Navigation</Breadcrumbs.Item>
      <Breadcrumbs.Item current>Breadcrumbs</Breadcrumbs.Item>
    </Breadcrumbs>
  );
};

Static Collapse

Set expandDisabled to display a non-interactive ellipsis. Hidden items cannot be revealed in this mode.

"use client";

import { Breadcrumbs } from "@vortexlabs/vortex";

export const BreadcrumbsStatic = () => {
  return (
    <Breadcrumbs
      ariaLabel="Compact breadcrumb"
      maxItems={2}
      maxItemsAriaLabel="Hidden parent pages"
      expandDisabled
    >
      <Breadcrumbs.Item href="/docs/introduction">Vortex</Breadcrumbs.Item>
      <Breadcrumbs.Item href="/docs/quick-start">Docs</Breadcrumbs.Item>
      <Breadcrumbs.Item href="/docs/all-components">Components</Breadcrumbs.Item>
      <Breadcrumbs.Item href="/docs/components/link">Navigation</Breadcrumbs.Item>
      <Breadcrumbs.Item current>Breadcrumbs</Breadcrumbs.Item>
    </Breadcrumbs>
  );
};

Accessibility

Key
Description
Provide ariaLabel for the navigation landmark. The path is rendered as an ordered list.
Set current on the current page. It receives aria-current="page", with or without a link.
Enter
Follow a focused breadcrumb link.
EnterSpace
Reveal hidden path items when the expand button is focused. Its accessible name comes from maxItemsAriaLabel.