Components

Breadcrumbs

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

Home
Services
Ticket System
Current Page

<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.

Home
Services
Ticket System
Del Water Gap

<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>

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.

<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.

<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)

Home
Government
Agencies
Parks & Recreation

<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.

Home
Services
Ticket System
Del Water Gap

<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.

Home
Services
Ticket System
Del Water Gap

<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

There are no existing CSS variables for this component. Explore existing options, or propose a new one with a Component Proposal.

Events

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

nys-expand – Fired when the button is clicked.

You can listen to these events using JavaScript:

// 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: June 18, 2026