Breadcrumbs

Introduction

The Breadcrumbs component provides a navigation aid that helps users understand their current location within a website’s hierarchy. It uses semantic HTML and follows WAI-ARIA best practices for navigation, ensuring both visual clarity and accessibility.

When to use

Breadcrumbs are perfect for websites with hierarchical navigation structures, helping users understand their location and navigate efficiently. They’re especially useful for:

• Multi-level navigation structures
• E-commerce product categories
• Documentation websites
• Content management systems
• Any site where showing the user’s location in the hierarchy is helpful

Quick example

1. Home /
2. Components /
3. Breadcrumbs /

Usage

Learn how to implement the Breadcrumbs component in your project, from basic usage to advanced variants.

Basic

---
import { Breadcrumbs, BreadcrumbsItem } from 'accessible-astro-components'
---

<Breadcrumbs>
  <BreadcrumbsItem href="/" label="Home" />
  <BreadcrumbsItem href="/products" label="Products" />
  <BreadcrumbsItem label="Current Page" currentPage={true} />
</Breadcrumbs>

Current page

Use the currentPage prop to indicate the current page in the breadcrumb trail. This will render it as a <span> instead of a link and add the appropriate ARIA attributes.

Variants

The BreadcrumbsItem component offers flexibility in its visual presentation through different separator styles and icon support.

<Breadcrumbs>
  {/* Home icon variant */}
  <BreadcrumbsItem href="/" label="Home" hasIcon>
    <Icon name="ion:home" slot="icon" />
  </BreadcrumbsItem>

  {/* Custom separator variant */}
  <BreadcrumbsItem href="/docs" label="Documentation">
    <span slot="separator" class="separator" aria-hidden="true">
      <Icon name="ion:chevron-forward-outline" />
    </span>
  </BreadcrumbsItem>

  <BreadcrumbsItem label="Current Page" currentPage={true} />
</Breadcrumbs>

Props

Configure the Breadcrumbs and BreadcrumbsItem components using these available props to customize their behavior and appearance.

Breadcrumbs

Prop	Type	Default	Description
class	string	''	Additional CSS classes to apply to the breadcrumbs wrapper
ariaLabel	string	'Breadcrumbs'	The label for the breadcrumbs navigation

BreadcrumbsItem

Prop	Type	Default	Description
href	string	'#'	The URL the breadcrumb item links to
label	string	'Breadcrumb'	The text to display (or screen reader text when using icons)
currentPage	boolean	false	Whether this item represents the current page
hasIcon	boolean	false	Whether this item displays an icon instead of text
class	string	''	Additional CSS classes to apply to the item

Accessibility

Accessibility isn’t an afterthought - it’s built into the core of this component through semantic HTML elements and careful consideration of user interactions. The Breadcrumbs component is built with accessibility in mind:

• Uses semantic <nav> element with appropriate aria-label
• Proper list structure with <ol> for screen readers
• Current page indicated with aria-current="page"
• Icons include screen reader text via sr-only class
• Separators are hidden from screen readers with aria-hidden="true"
• Automatic light/dark mode color adaptation

User preferences

The component automatically respects user preferences for reduced motion and color scheme.

Styling

Make the Breadcrumbs component your own with custom styling while maintaining its accessibility features.

Accessibility considerations

When applying custom styles, ensure they don’t compromise accessibility by maintaining sufficient color contrast and touch target sizes.

Custom CSS

/* Option 1: Using :global() in your style block */
<style>
  :global(.breadcrumbs .list) {
    display: flex;
    align-items: center;
    gap: 0.5rem;
  }

  :global(.breadcrumbs a) {
    color: light-dark(hsl(215 25% 27%), hsl(215 25% 89%));
    text-decoration: none;
  }

  :global(.breadcrumbs a:hover) {
    text-decoration: underline;
  }

  :global(.breadcrumbs .separator) {
    color: light-dark(hsl(215 8% 45%), hsl(215 8% 65%));
  }
</style>

/* Option 2: Using is:global on the style tag */
<style is:global>
  .breadcrumbs .list {
    display: flex;
    align-items: center;
    gap: 0.5rem;
  }

  .breadcrumbs a {
    color: light-dark(hsl(215 25% 27%), hsl(215 25% 89%));
    text-decoration: none;
  }

  .breadcrumbs a:hover {
    text-decoration: underline;
  }

  .breadcrumbs .separator {
    color: light-dark(hsl(215 8% 45%), hsl(215 8% 65%));
  }
</style>

Tailwind Classes

<Breadcrumbs class="text-gray-600 dark:text-gray-400">
  <BreadcrumbsItem
    href="/"
    label="Home"
    class="hover:text-gray-900 dark:hover:text-gray-100"
  >
    <span slot="separator" class="text-gray-400 dark:text-gray-600">
      <Icon name="ion:chevron-forward" />
    </span>
  </BreadcrumbsItem>
</Breadcrumbs>

Style scoping

Astro components use scoped styles by default. To override component styles, you’ll need to use either :global() selectors or the is:global directive on your style tag.

Interactive examples

See the Breadcrumbs component in action with these practical examples demonstrating different variants and styling options.

Default style

1. Home /
2. Documentation /
3. Breadcrumbs /

With home icon

1. Home /
2. Documentation /
3. Breadcrumbs /

Custom separator

1. Home
2. Documentation
3. Breadcrumbs /