breadcrumb.tsx

Overview

breadcrumb.tsx provides a set of accessible, reusable React components designed to build a breadcrumb navigation UI. Breadcrumb navigation helps users understand their location within a website or application hierarchy and quickly navigate back to previous pages.

This file exports a modular breadcrumb system composed of several components representing the navigation container, list, individual breadcrumb items, links, separators, and special indicators like ellipsis for overflow. The components emphasize accessibility (ARIA attributes), styling flexibility, and composability with support for custom elements and separators.

Components and Their Details

1. Breadcrumb

• Type: React ForwardRef Component

• Element Rendered: <nav>

• Props:

  • Standard nav element props (React.ComponentPropsWithoutRef<'nav'>)

  • separator?: React.ReactNode (optional, not directly used in this component but can be passed down or used externally)

• Purpose: Acts as the navigation container for the breadcrumb trail.

• Accessibility: Uses aria-label="breadcrumb" to indicate the purpose of the navigation landmark.

• Usage example:

  <Breadcrumb>
    {/* BreadcrumbList and children go here */}
  </Breadcrumb>
  

2. BreadcrumbList

• Type: React ForwardRef Component

• Element Rendered: <ol> (ordered list)

• Props: Standard ordered list props (React.ComponentPropsWithoutRef<'ol'>)

• Purpose: Container for breadcrumb items. Uses flexbox for layout with responsive styling.

• Styling: Applies utility classes for spacing, text size, color, and line wrapping (flex flex-wrap items-center gap-1.5 break-words text-sm text-muted-foreground sm:gap-2.5)

• Usage example:

  <BreadcrumbList>
    <BreadcrumbItem>...</BreadcrumbItem>
    <BreadcrumbItem>...</BreadcrumbItem>
  </BreadcrumbList>
  

3. BreadcrumbItem

• Type: React ForwardRef Component

• Element Rendered: <li>

• Props: Standard list item props (React.ComponentPropsWithoutRef<'li'>)

• Purpose: Represents an individual breadcrumb item.

• Styling: Inline-flex container for aligning item content with spacing (inline-flex items-center gap-1.5 text-text-secondary)

• Usage example:

  <BreadcrumbItem>
    <BreadcrumbLink href="/dashboard">Dashboard</BreadcrumbLink>
  </BreadcrumbItem>
  

4. BreadcrumbLink

• Type: React ForwardRef Component

• Element Rendered: Either <a> or a custom component via Slot from @radix-ui/react-slot

• Props:

  • Standard anchor props (React.ComponentPropsWithoutRef<'a'>)

  • asChild?: boolean (optional) — if true, renders a child component instead of <a>.

• Purpose: Clickable breadcrumb link to navigate to an intermediate page.

• Styling: Adds hover color transitions (transition-colors hover:text-foreground)

• Implementation Details:

  • Uses Slot to allow rendering any custom element while preserving ref forwarding and styling.

• Usage example:

  <BreadcrumbLink href="/profile">Profile</BreadcrumbLink>
  
  // Using custom component as child
  <BreadcrumbLink asChild>
    <CustomLinkComponent to="/profile" />
  </BreadcrumbLink>
  

5. BreadcrumbPage

• Type: React ForwardRef Component

• Element Rendered: <span>

• Props: Standard span props (React.ComponentPropsWithoutRef<'span'>)

• Purpose: Represents the current page in the breadcrumb trail (non-clickable).

• Accessibility:

  • role="link" to indicate link semantics

  • aria-disabled="true" disables interaction

  • aria-current="page" marks this as the active/current breadcrumb

• Styling: Highlights the current page with font-normal text-foreground.

• Usage example:

  <BreadcrumbPage>Settings</BreadcrumbPage>
  

6. BreadcrumbSeparator

• Type: Functional Component

• Element Rendered: <li>

• Props: Standard <li> props (React.ComponentProps<'li'>), plus optional children.

• Purpose: Visual separator between breadcrumb items, typically a right-pointing chevron.

• Accessibility:

  • role="presentation" and aria-hidden="true" hides it from assistive technologies.

• Default Content: Uses <ChevronRight /> icon from lucide-react if no children specified.

• Styling: Sets fixed icon size ([&>svg]:w-3.5 [&>svg]:h-3.5)

• Usage example:

  <BreadcrumbSeparator />
  // or custom separator
  <BreadcrumbSeparator>></BreadcrumbSeparator>
  

7. BreadcrumbEllipsis

• Type: Functional Component

• Element Rendered: <span>

• Props: Standard span props (React.ComponentProps<'span'>)

• Purpose: Indicates overflow of breadcrumb items when the breadcrumb list is too long (e.g., "More" indicator).

• Accessibility:

  • role="presentation" and aria-hidden="true" hides it visually but includes a screen-reader-only label "More".

• Content: Renders <MoreHorizontal /> icon from lucide-react with hidden text for screen readers.

• Styling: Centers icon in a 9x9 flexbox container.

• Usage example:

  <BreadcrumbEllipsis />
  

Implementation Details & Algorithms

• Ref Forwarding: All main components use React.forwardRef to allow parent components to directly reference underlying DOM nodes.

• Class Name Composition: Uses a utility function cn (class name concatenation) imported from @/lib/utils to combine default and user-supplied class names safely.

• Accessibility (ARIA):

  • Breadcrumb uses aria-label="breadcrumb" on <nav>.

  • BreadcrumbPage marks current page with aria-current="page".

  • Separators and ellipsis use aria-hidden="true" and role="presentation" to avoid screen reader clutter.

• Custom Render as Child: BreadcrumbLink supports rendering custom components via Radix UI's Slot component, enabling advanced composition without losing accessibility or styling.

• Icon Usage: Chevron and Ellipsis icons are provided by lucide-react for consistent visual language.

Interaction with Other Parts of the System

• Styling Utilities: Relies on cn function from @/lib/utils for class name management.

• Icon Library: Uses lucide-react for SVG icons that match the app's design system.

• Radix UI Slot: Uses @radix-ui/react-slot to support polymorphic children in BreadcrumbLink.

• Application Usage: These components would be integrated into page layouts or navigation components to display hierarchical paths. The modular design allows flexible assembly depending on the breadcrumb complexity (simple vs. truncated with ellipsis).

Usage Example

import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
  BreadcrumbPage,
} from './breadcrumb';

function DemoBreadcrumb() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="/">Home</BreadcrumbLink>
          <BreadcrumbSeparator />
        </BreadcrumbItem>
        <BreadcrumbItem>
          <BreadcrumbLink href="/category">Category</BreadcrumbLink>
          <BreadcrumbSeparator />
        </BreadcrumbItem>
        <BreadcrumbItem>
          <BreadcrumbPage>Current Page</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  );
}

Mermaid Component Diagram

componentDiagram
    direction LR
    Breadcrumb <|-- BreadcrumbList
    BreadcrumbList *-- BreadcrumbItem
    BreadcrumbItem *-- BreadcrumbLink
    BreadcrumbItem *-- BreadcrumbSeparator
    BreadcrumbItem *-- BreadcrumbPage
    BreadcrumbList *-- BreadcrumbEllipsis

    component Breadcrumb {
      +forwardRef(nav)
      +aria-label="breadcrumb"
    }
    component BreadcrumbList {
      +forwardRef(ol)
      +flex layout
    }
    component BreadcrumbItem {
      +forwardRef(li)
      +flex align
    }
    component BreadcrumbLink {
      +forwardRef(a or Slot)
      +asChild?: boolean
    }
    component BreadcrumbPage {
      +forwardRef(span)
      +aria-current="page"
    }
    component BreadcrumbSeparator {
      +li role="presentation"
      +default ChevronRight icon
    }
    component BreadcrumbEllipsis {
      +span role="presentation"
      +MoreHorizontal icon
    }

Summary

The breadcrumb.tsx file supplies a clean, accessible, and flexible breadcrumb navigation system built with React. It focuses on semantic markup, ARIA accessibility, and composability with support for custom components and icons. This file is intended to be used as a foundational UI element for hierarchical navigation in larger React applications.