Breadcrumbs

Breadcrumbs show users their current location within a website's hierarchy and help them navigate back to parent pages.

Installation

Add the breadcrumbs component to your project:

npx velyx add breadcrumbs

pnpm dlx velyx add breadcrumbs

yarn dlx velyx add breadcrumbs

bunx --bun velyx add breadcrumbs

Usage

Default Breadcrumbs

<x-ui.breadcrumbs :items="[
        ['label' => 'Home', 'url' => '/'],
        ['label' => 'Components', 'url' => '/components'],
        ['label' => 'Navigation', 'url' => '/components/navigation'],
        ['label' => 'Breadcrumbs'],
    ]" />

Custom Separator

<x-ui.breadcrumbs
        :items="[
            ['label' => 'Home', 'url' => '/'],
            ['label' => 'Components', 'url' => '/components'],
            ['label' => 'Navigation', 'url' => '/components/navigation'],
        ]"
        separator=">"
    />

<x-ui.breadcrumbs
        :items="[
            ['label' => 'Home', 'url' => '/'],
            ['label' => 'Docs', 'url' => '/docs'],
            ['label' => 'Components', 'url' => '/docs/components'],
        ]"
        separator="→"
    />

<x-ui.breadcrumbs
        :items="[
            ['label' => 'Home', 'url' => '/'],
            ['label' => 'Library', 'url' => '/library'],
            ['label' => 'Books', 'url' => '/library/books'],
        ]"
        separator="•"
    />

With Home Icon

<x-ui.breadcrumbs
        :items="[
            ['label' => 'Home', 'url' => '/'],
            ['label' => 'Products', 'url' => '/products'],
            ['label' => 'Category', 'url' => '/products/category'],
        ]"
        :home-icon="true"
    />

Props

Items Structure

Each breadcrumb item in the items array should have:

[
    'label' => 'Display Text',  // Required: Text to show
    'url' => '/path'            // Optional: URL for navigation
]

The last item typically doesn't have a URL to indicate the current page.

Examples

Simple Navigation

<x-ui.breadcrumbs :items="[
    ['label' => 'Home', 'url' => '/'],
    ['label' => 'Products', 'url' => '/products'],
    ['label' => 'Laptop'],
]" />

Product Hierarchy

<x-ui.breadcrumbs :items="[
    ['label' => 'Home', 'url' => '/'],
    ['label' => 'Shop', 'url' => '/shop'],
    ['label' => 'Computers', 'url' => '/shop/computers'],
    ['label' => 'Laptops', 'url' => '/shop/computers/laptops'],
    ['label' => 'MacBook Pro'],
]" />

Documentation Structure

<x-ui.breadcrumbs :items="[
    ['label' => 'Home', 'url' => '/'],
    ['label' => 'Documentation', 'url' => '/docs'],
    ['label' => 'Components', 'url' => '/docs/components'],
    ['label' => 'Button', 'url' => '/docs/components/button'],
]" />

Blog Categories

<x-ui.breadcrumbs
    :items="[
        ['label' => 'Home', 'url' => '/'],
        ['label' => 'Blog', 'url' => '/blog'],
        ['label' => 'Technology', 'url' => '/blog/tech'],
    ]"
    separator=">"
/>

Custom Styling

<div class="flex items-center gap-2 text-sm">
    <x-ui.breadcrumbs :items="$breadcrumbs" class="text-muted-foreground" />
</div>

With Icons

<x-ui.breadcrumbs
    :items="[
        ['label' => 'Home', 'url' => '/'],
        ['label' => 'Settings', 'url' => '/settings'],
        ['label' => 'Profile', 'url' => '/settings/profile'],
    ]"
    :home-icon="true"
    separator="→"
/>

Accessibility

Breadcrumbs include proper ARIA attributes and semantic HTML:

• <nav> element with aria-label="Breadcrumbs"
• Ordered list structure
• Proper landmark navigation
• Clear visual hierarchy
• Keyboard navigation support

Customization

The breadcrumbs component uses Tailwind CSS classes. You can customize the appearance by modifying the component in your project:

@

@props([
    'items' => [],
    'separator' => '/',
    'homeIcon' => false,
])

// Customize styling, separators, and structure

Separator Options

Common separators you can use: - / (default) - Forward slash - > - Greater than - → - Right arrow - » - Double right arrow - • - Bullet - | - Pipe

Styling Current Page

The last breadcrumb (current page) is automatically styled differently to indicate it's not clickable:

// Last item gets different styling
<li class="text-foreground font-medium" aria-current="page">
    Current Page
</li>

Best Practices

Keep It Short

Limit breadcrumbs to show only the most relevant path levels:

@
<x-ui.breadcrumbs :items="[
    ['label' => 'Home', 'url' => '/'],
    ['label' => 'Products', 'url' => '/products'],
    ['label' => 'Category'],
]" />

@
<x-ui.breadcrumbs :items="[
    ['label' => 'Home', 'url' => '/'],
    ['label' => 'Shop', 'url' => '/shop'],
    ['label' => 'Products', 'url' => '/shop/products'],
    ['label' => 'Category', 'url' => '/shop/products/cat'],
    ['label' => 'Subcategory', 'url' => '/shop/products/cat/sub'],
    ['label' => 'Item'],
]" />

Use Meaningful Labels

Keep breadcrumb labels short and descriptive:

@
['label' => 'Products', 'url' => '/products']

@
['label' => 'Click here to view our products', 'url' => '/products']

Next Steps

• Explore Navigation components
• Learn about Separator component
• View Dropdown Menu component