View as Markdown

Breadcrumb

Displays the path to the current resource using a hierarchy of links.

100%
Loading... 
<twig:Breadcrumb>
    <twig:Breadcrumb:List>
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Link href="#">Home</twig:Breadcrumb:Link>
        </twig:Breadcrumb:Item>
        <twig:Breadcrumb:Separator />
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Ellipsis />
        </twig:Breadcrumb:Item>
        <twig:Breadcrumb:Separator />
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Link href="#">Components</twig:Breadcrumb:Link>
        </twig:Breadcrumb:Item>
        <twig:Breadcrumb:Separator />
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Page>Breadcrumb</twig:Breadcrumb:Page>
        </twig:Breadcrumb:Item>
    </twig:Breadcrumb:List>
</twig:Breadcrumb>

Installation

php bin/console ux:install breadcrumb --kit shadcn

Install the following Composer dependencies:

composer require symfony/ux-icons twig/html-extra:^3.24.0 symfony/ux-twig-component:^3.5 tales-from-a-dev/twig-tailwind-extra:^1.3.0

Copy the following file(s) into your app:

templates/components/Breadcrumb.html.twig 
<nav
    data-slot="breadcrumb"
    aria-label="breadcrumb"
    {{ attributes }}
>
    {##- The breadcrumb structure, typically a `Breadcrumb:List`. -#}
    {%- block content %}{% endblock -%}
</nav>
templates/components/Breadcrumb/Ellipsis.html.twig 
<span
    data-slot="breadcrumb-ellipsis"
    role="presentation"
    aria-hidden="true"
    {{ attributes.defaults({
        class: 'flex size-5 items-center justify-center [&>svg]:size-4'|tailwind_classes,
    }) }}
>
    <twig:ux:icon name="lucide:ellipsis" />
    <span class="sr-only">More</span>
</span>
templates/components/Breadcrumb/Item.html.twig 
<li
    data-slot="breadcrumb-item"
    {{ attributes.defaults({
        class: 'inline-flex items-center gap-1'|tailwind_classes,
    }) }}
>
    {##- The breadcrumb item content, typically a `Breadcrumb:Link` or `Breadcrumb:Page`. -#}
    {%- block content %}{% endblock -%}
</li>
templates/components/Breadcrumb/Link.html.twig 
<a
    data-slot="breadcrumb-link"
    {{ attributes.defaults({
        class: 'transition-colors hover:text-foreground'|tailwind_classes,
    }) }}
>
    {##- The clickable link text. -#}
    {%- block content %}{% endblock -%}
</a>
templates/components/Breadcrumb/List.html.twig 
<ol
    data-slot="breadcrumb-list"
    {{ attributes.defaults({
        class: 'flex flex-wrap items-center gap-1.5 text-sm wrap-break-word text-muted-foreground'|tailwind_classes,
    }) }}
>
    {##- The list of breadcrumb items, typically multiple `Breadcrumb:Item` components. -#}
    {%- block content %}{% endblock -%}
</ol>
templates/components/Breadcrumb/Page.html.twig 
<span
    data-slot="breadcrumb-page"
    role="link"
    aria-disabled="true"
    aria-current="page"
    {{ attributes.defaults({
        class: 'font-normal text-foreground'|tailwind_classes,
    }) }}
>
    {##- The current page text (non-clickable). -#}
    {%- block content %}{% endblock -%}
</span>
templates/components/Breadcrumb/Separator.html.twig 
<li
    data-slot="breadcrumb-separator"
    role="presentation"
    aria-hidden="true"
    {{ attributes.defaults({
        class: '[&>svg]:size-3.5'|tailwind_classes,
    }) }}
>
    {##- The separator icon between breadcrumb items, defaults to a chevron. -#}
    {%- block content -%}
        <twig:ux:icon name="lucide:chevron-right" class="rtl:rotate-180" />
    {%- endblock %}
</li>

Usage

<twig:Breadcrumb>
    <twig:Breadcrumb:List>
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Link href="#">Home</twig:Breadcrumb:Link>
        </twig:Breadcrumb:Item>
        <twig:Breadcrumb:Separator />
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Link href="#">Components</twig:Breadcrumb:Link>
        </twig:Breadcrumb:Item>
        <twig:Breadcrumb:Separator />
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Page>Breadcrumb</twig:Breadcrumb:Page>
        </twig:Breadcrumb:Item>
    </twig:Breadcrumb:List>
</twig:Breadcrumb>

Examples

Basic

A basic breadcrumb with a home link and a components link.

100%
Loading... 
<twig:Breadcrumb>
    <twig:Breadcrumb:List>
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Link href="#">Home</twig:Breadcrumb:Link>
        </twig:Breadcrumb:Item>
        <twig:Breadcrumb:Separator />
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Link href="#">Components</twig:Breadcrumb:Link>
        </twig:Breadcrumb:Item>
        <twig:Breadcrumb:Separator />
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Page>Breadcrumb</twig:Breadcrumb:Page>
        </twig:Breadcrumb:Item>
    </twig:Breadcrumb:List>
</twig:Breadcrumb>

Custom separator

Use a custom component as children for Breadcrumb:Separator to create a custom separator.

100%
Loading... 
<twig:Breadcrumb>
    <twig:Breadcrumb:List>
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Link href="#">Home</twig:Breadcrumb:Link>
        </twig:Breadcrumb:Item>
        <twig:Breadcrumb:Separator>
            <twig:ux:icon name="lucide:dot" />
        </twig:Breadcrumb:Separator>
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Link href="#">Components</twig:Breadcrumb:Link>
        </twig:Breadcrumb:Item>
        <twig:Breadcrumb:Separator>
            <twig:ux:icon name="lucide:dot" />
        </twig:Breadcrumb:Separator>
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Page>Breadcrumb</twig:Breadcrumb:Page>
        </twig:Breadcrumb:Item>
    </twig:Breadcrumb:List>
</twig:Breadcrumb>

Collapsed

We provide a Breadcrumb:Ellipsis component to show a collapsed state when the breadcrumb is too long.

100%
Loading... 
<twig:Breadcrumb>
    <twig:Breadcrumb:List>
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Link href="#">Home</twig:Breadcrumb:Link>
        </twig:Breadcrumb:Item>
        <twig:Breadcrumb:Separator />
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Ellipsis />
        </twig:Breadcrumb:Item>
        <twig:Breadcrumb:Separator />
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Link href="#">Components</twig:Breadcrumb:Link>
        </twig:Breadcrumb:Item>
        <twig:Breadcrumb:Separator />
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Page>Breadcrumb</twig:Breadcrumb:Page>
        </twig:Breadcrumb:Item>
    </twig:Breadcrumb:List>
</twig:Breadcrumb>

Link component

To use a custom link component from your routing library, you can pass the href attribute to Breadcrumb:Link.

100%
Loading... 
<twig:Breadcrumb>
    <twig:Breadcrumb:List>
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Link href="#">Home</twig:Breadcrumb:Link>
        </twig:Breadcrumb:Item>
        <twig:Breadcrumb:Separator />
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Link href="#">Components</twig:Breadcrumb:Link>
        </twig:Breadcrumb:Item>
        <twig:Breadcrumb:Separator />
        <twig:Breadcrumb:Item>
            <twig:Breadcrumb:Page>Breadcrumb</twig:Breadcrumb:Page>
        </twig:Breadcrumb:Item>
    </twig:Breadcrumb:List>
</twig:Breadcrumb>

RTL

To enable RTL support, set the dir="rtl" attribute on the root element.

100%
Loading... 
<div class="flex flex-col gap-6">
    <twig:Breadcrumb dir="rtl">
        <twig:Breadcrumb:List>
            <twig:Breadcrumb:Item>
                <twig:Breadcrumb:Link href="#">الرئيسية</twig:Breadcrumb:Link>
            </twig:Breadcrumb:Item>
            <twig:Breadcrumb:Separator>
                <twig:ux:icon name="lucide:dot" />
            </twig:Breadcrumb:Separator>
            <twig:Breadcrumb:Item>
                <twig:Breadcrumb:Link href="#">المكونات</twig:Breadcrumb:Link>
            </twig:Breadcrumb:Item>
            <twig:Breadcrumb:Separator>
                <twig:ux:icon name="lucide:dot" />
            </twig:Breadcrumb:Separator>
            <twig:Breadcrumb:Item>
                <twig:Breadcrumb:Page>مسار التنقل</twig:Breadcrumb:Page>
            </twig:Breadcrumb:Item>
        </twig:Breadcrumb:List>
    </twig:Breadcrumb>
    <twig:Breadcrumb dir="rtl">
        <twig:Breadcrumb:List>
            <twig:Breadcrumb:Item>
                <twig:Breadcrumb:Link href="#">בית</twig:Breadcrumb:Link>
            </twig:Breadcrumb:Item>
            <twig:Breadcrumb:Separator>
                <twig:ux:icon name="lucide:dot" />
            </twig:Breadcrumb:Separator>
            <twig:Breadcrumb:Item>
                <twig:Breadcrumb:Link href="#">רכיבים</twig:Breadcrumb:Link>
            </twig:Breadcrumb:Item>
            <twig:Breadcrumb:Separator>
                <twig:ux:icon name="lucide:dot" />
            </twig:Breadcrumb:Separator>
            <twig:Breadcrumb:Item>
                <twig:Breadcrumb:Page>ניווט</twig:Breadcrumb:Page>
            </twig:Breadcrumb:Item>
        </twig:Breadcrumb:List>
    </twig:Breadcrumb>
</div>

Accessibility

  • Breadcrumb renders a <nav> landmark with aria-label="breadcrumb", and Breadcrumb:List a real <ol>, so the trail is announced as an ordered navigation.
  • Breadcrumb:Page marks the current page with aria-current="page", and carries role="link" with aria-disabled="true" so it reads as the link you are already on rather than as plain text.
  • Breadcrumb:Separator is hidden with aria-hidden="true" and role="presentation", so the chevron between items is never read out.
  • Breadcrumb:Ellipsis is hidden the same way but carries a visually hidden "More" label, so the collapsed part of the trail is still explained.
  • Keep the trail in document order from the root to the current page. The reading order is the markup order, whatever the styling does.

API Reference

<twig:Breadcrumb>

Block Description
content The breadcrumb structure, typically a Breadcrumb:List.

<twig:Breadcrumb:Item>

Block Description
content The breadcrumb item content, typically a Breadcrumb:Link or Breadcrumb:Page.

<twig:Breadcrumb:Link>

Block Description
content The clickable link text.

<twig:Breadcrumb:List>

Block Description
content The list of breadcrumb items, typically multiple Breadcrumb:Item components.

<twig:Breadcrumb:Page>

Block Description
content The current page text (non-clickable).

<twig:Breadcrumb:Separator>

Block Description
content The separator icon between breadcrumb items, defaults to a chevron.