Breadcrumbs

The <nys-breadcrumbs> component shows users their location within a site's structure and provides links to navigate back through parent pages.

  1. Home
  2. Services
  3. Ticket System
  4. Current Page
Copy Code
<nys-breadcrumbs>
  <ol>
    <li><a href="/">Home</a></li>
    <li><a href="/services">Services</a></li>
    <li><a href="/tickets">Ticket System</a></li>
    <li>Current Page</li>
  </ol>
</nys-breadcrumbs>

Can't use NYS Design System web components in your project? Try using the CSS Variables instead.


Accessibility

Breadcrumbs test status
Total tests Passes Fails To do
22 22 0 0

For comprehensive insight and guidance, please see Accessibility Checklists and Build Accessibly.


Options

Basic Usage

Wrap an ordered list (<ol>) with links (<a>) inside <nys-breadcrumbs>. The last <li> should be plain text (the current page).

Note: If you prefer not to display the current page in the breadcrumb trail, simply leave it out.

  1. Home
  2. Services
  3. Ticket System
  4. Del Water Gap
Copy Code
<nys-breadcrumbs>
  <ol>
    <li><a href="/">Home</a></li>
    <li><a href="/services">Services</a></li>
    <li><a href="/tickets">Ticket System</a></li>
    <li>Del Water Gap</li>
  </ol>
</nys-breadcrumbs>

Single Item List

When only one <li> is provided, the component renders it as a back-to-parent link instead of a trail.

  1. Services
Copy Code
<nys-breadcrumbs>
  <ol>
    <li><a href="/services">Services</a></li>
  </ol>
</nys-breadcrumbs>

Collapsed

Add the collapsed prop to render the breadcrumb trail in its collapsed state. Users can expand the full trail by selecting the ellipsis.

Breadcrumbs automatically collapse when the trail exceeds 5 items on desktop or 3 items on mobile.

  1. Home
  2. Government
  3. Agencies
  4. Parks & Recreation
  5. State Parks
  6. Delaware Region
  7. Delaware Water Gap
  8. Trail Conditions
Copy Code
<nys-breadcrumbs collapsed>
  <ol>
    <li><a href="/">Home</a></li>
    <li><a href="/government">Government</a></li>
    <li><a href="/government/agencies">Agencies</a></li>
    <li><a href="/government/agencies/parks">Parks & Recreation</a></li>
    <li><a href="/parks/state-parks">State Parks</a></li>
    <li><a href="/parks/state-parks/delaware">Delaware Region</a></li>
    <li><a href="/parks/state-parks/delaware/water-gap">Delaware Water Gap</a></li>
    <li>Trail Conditions</li>
  </ol>
</nys-breadcrumbs>

Back to Parent (Mobile Only)

Add the backToParent prop to collapse the full breadcrumb trail into a single "back to parent" button on screens narrower than 767px. The component automatically determines which crumb represents the parent of the current page. Resize your browser to a small width to see it in action.

  1. Home
  2. Government
  3. Agencies
  4. Parks & Recreation
  5. State Parks
  6. Delaware Region
  7. Delaware Water Gap
  8. Trail Conditions
Copy Code
<nys-breadcrumbs backToParent>
  <ol>
    <li><a href="/">Home</a></li>
    <li><a href="/government">Government</a></li>
    <li><a href="/government/agencies">Agencies</a></li>
    <li><a href="/government/agencies/parks">Parks & Recreation</a></li>
    <li><a href="/parks/state-parks">State Parks</a></li>
    <li><a href="/parks/state-parks/delaware">Delaware Region</a></li>
    <li><a href="/parks/state-parks/delaware/water-gap">Delaware Water Gap</a></li>
    <li>Trail Conditions</li>
  </ol>
</nys-breadcrumbs>

Size

Set the size prop to adjust text size. Available sizes:

  • md: Default size (16px)
  • sm: Smaller text (14px)
  1. Home
  2. Government
  3. Agencies
  4. Parks & Recreation
Copy Code
<nys-breadcrumbs size="sm">
  <ol>
    <li><a href="/">Home</a></li>
    <li><a href="/government">Government</a></li>
    <li><a href="/government/agencies">Agencies</a></li>
    <li>Parks & Recreation</li>
  </ol>
</nys-breadcrumbs>

Background Bar

Add the backgroundBar prop to display breadcrumbs on a light gray background bar.

  1. Home
  2. Services
  3. Ticket System
  4. Del Water Gap
Copy Code
<nys-breadcrumbs backgroundBar>
  <ol>
    <li><a href="/">Home</a></li>
    <li><a href="/services">Services</a></li>
    <li><a href="/tickets">Ticket System</a></li>
    <li>Del Water Gap</li>
  </ol>
</nys-breadcrumbs>

Disabled

Add the disabled prop to disable all links in the breadcrumbs.

  1. Home
  2. Services
  3. Ticket System
  4. Del Water Gap
Copy Code
<nys-breadcrumbs disabled>
  <ol>
    <li><a href="/">Home</a></li>
    <li><a href="/services">Services</a></li>
    <li><a href="/tickets">Ticket System</a></li>
    <li>Del Water Gap</li>
  </ol>
</nys-breadcrumbs>

Usage

Do

  • Use on pages at level 2 and deeper in a site hierarchy. If a level 2 page has child pages, all pages starting at that level should include a breadcrumb.
  • Place breadcrumb below the header and above the main content.
  • Show the site hierarchy, not the path a user took.
  • For the home page of a site, use a specific label rather than a generic "Home." This differentiates the main site home from other landing pages (e.g., "myBenefits Home" instead of just "Home").

Don't

  • Don't use on top-level pages, or on sites with only one or two levels of hierarchy.
  • Don't make the current page clickable.
  • Don't use breadcrumbs as the only navigation method.
  • Don't use breadcrumbs for sequential processes like multi-step forms or wizards. Use a stepper instead.
  • Don't add breadcrumbs when they don't provide meaningful context or navigation value.

Properties

Property Type Default
id String Auto-generated
size "sm", "md" "md"
ariaLabel String "Breadcrumbs"
collapsed Boolean false
backToParent Boolean false
backgroundBar Boolean false
disabled Boolean false

Style Overrides

These CSS custom properties are exposed for developers to customize the visual appearance of the component when necessary, beyond the defaults provided by the NYS Design System. Set them on the component selector to override the default styles.

Copy Code
nys-component {
  --nys-component-background-color: var(--nys-color-accent);
  --nys-component-color: var(--nys-color-ink);
}

CSS Variable Description
--nys-max-width--content Overrides the max width of the inner content area on .nys-grid-container and all header/footer/breadcrumb components at once. Set this at a higher level (e.g. :root) so it cascades down to every instance — setting it directly on one component only affects that instance. Takes priority over the size-specific variable below.
--_nys-breadcrumbs-max-width--content The maximum width for this inner container size. Falls back to the size's default (e.g. 1280px) if not set.
Can't find a property you need? Explore existing options, or propose a new one with a Component Proposal.


Events

Some components emit nys- events with a detail object containing the relevant data, instead of relying on native events alone. Stick to one approach per interaction, don't mix native and nys- listeners for the same thing.

The <nys-breadcrumbs> component emits one custom Javascript event:

Event details

Name Description Return details
nys-expand Fired when the collapsed breadcrumb trail is expanded. —

You can listen to these events using JavaScript:

Copy Code
// Select the breadcrumbs component
const breadcrumbs = document.querySelector('nys-breadcrumbs');
// Listen for the 'nys-expand' event
breadcrumbs.addEventListener("nys-expand", () => {
  console.log("Breadcrumbs expanded");
});

Suggest a New Component

Do you have an idea for a new NYS Design System web component? Look through the existing proposals in our GitHub discussions board to see if someone already proposed something similar. If not, feel free to submit one.

Edit this page on GitHub (Permissions required)

Last updated: September 28, 2026