Breadcrumbs

Use CBreadcrumbs to show the current page within a hierarchy and link back to its ancestors.

Breadcrumbs at a glance

Show code

import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class BreadcrumbsAtAGlance(Component):
    class Kwargs:
        pass

    class Slots:
        pass

    def template_data(self, kwargs: Kwargs, slots: Slots) -> dict[str, object]:  # noqa: ARG002
        return {
            "items": (
                citry_ui.CBreadcrumbItem("Library", "/library"),
                citry_ui.CBreadcrumbItem("Natural history", "/library/nature"),
                citry_ui.CBreadcrumbItem("The hidden life of trees"),
            )
        }

    template = """
      <section class="breadcrumb-shelf">
        <c-CBreadcrumbs c-items="items" label="Book location" />
        <h2>The hidden life of trees</h2>
        <p>Essays on forests, roots, and the communities beneath them.</p>
      </section>
    """
    css = """
      :where(.breadcrumb-shelf) {
        display: grid;
        gap: 0.75rem;
        max-inline-size: 42rem;
        padding: 1.25rem;
        border: 1px solid light-dark(#b8aa92, #655a49);
        border-radius: 0.9rem;
        color: CanvasText;
        font-family: ui-serif, Georgia, serif;
      }

      :where(.breadcrumb-shelf h2, .breadcrumb-shelf p) {
        margin: 0;
      }
    """


preview = BreadcrumbsAtAGlance()

preview  # noqa: B018

Build a trail from records

The final item is current. Give earlier items an href; leave the final href empty for plain current-page text.

Build a Breadcrumb trail

Show code

import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class BasicBreadcrumbs(Component):
    class Kwargs:
        pass

    class Slots:
        pass

    def template_data(self, kwargs: Kwargs, slots: Slots) -> dict[str, object]:  # noqa: ARG002
        return {
            "items": (
                citry_ui.CBreadcrumbItem("Library", "/library"),
                citry_ui.CBreadcrumbItem("Fiction", "/library/fiction"),
                citry_ui.CBreadcrumbItem("The left hand of darkness"),
            )
        }

    template = '<c-CBreadcrumbs c-items="items" label="Book location" />'


preview = BasicBreadcrumbs()

preview  # noqa: B018

items = (
    CBreadcrumbItem("Home", "/"),
    CBreadcrumbItem("Library", "/library"),
    CBreadcrumbItem("The green room"),
)

Keep the current page linked

A final item may retain its href. Citry adds aria-current="page".

Link the current page

Show code

import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class LinkedCurrentBreadcrumb(Component):
    class Kwargs:
        pass

    class Slots:
        pass

    def template_data(self, kwargs: Kwargs, slots: Slots) -> dict[str, object]:  # noqa: ARG002
        return {
            "items": (
                citry_ui.CBreadcrumbItem("Library", "/library"),
                citry_ui.CBreadcrumbItem("New arrivals", "/library/new"),
            )
        }

    template = '<c-CBreadcrumbs c-items="items" label="Collection location" />'


preview = LinkedCurrentBreadcrumb()

preview  # noqa: B018

Choose a separator

Use concise text directly or replace each separator through the scoped slot. Separators stay hidden from assistive technology.

Choose Breadcrumb separators

Show code

import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class BreadcrumbSeparators(Component):
    class Kwargs:
        pass

    class Slots:
        pass

    def template_data(self, kwargs: Kwargs, slots: Slots) -> dict[str, object]:  # noqa: ARG002
        return {
            "items": (
                citry_ui.CBreadcrumbItem("Poetry", "/poetry"),
                citry_ui.CBreadcrumbItem("Mary Oliver"),
            )
        }

    template = """
      <c-CStack>
        <c-CBreadcrumbs c-items="items" separator="/" label="Slash trail" />
        <c-CBreadcrumbs c-items="items" separator="»" label="Chevron trail" />
        <c-CBreadcrumbs c-items="items" label="Arrow trail">
          <c-fill name="separator" data="{ index }">
            →
          </c-fill>
        </c-CBreadcrumbs>
      </c-CStack>
    """


preview = BreadcrumbSeparators()

preview  # noqa: B018

Choose size

Use sm, md, or lg to match the surrounding navigation density.

Compare Breadcrumb sizes

Show code

import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class BreadcrumbSizes(Component):
    class Kwargs:
        pass

    class Slots:
        pass

    def template_data(self, kwargs: Kwargs, slots: Slots) -> dict[str, object]:  # noqa: ARG002
        return {
            "items": (
                citry_ui.CBreadcrumbItem("Essays", "/essays"),
                citry_ui.CBreadcrumbItem("On keeping a notebook"),
            ),
            "sizes": ("sm", "md", "lg"),
        }

    template = """
      <c-CStack>
        <c-for each="size in sizes">
          <c-CBreadcrumbs c-items="items" c-size="size" c-label="f'{size} book location'" />
        </c-for>
      </c-CStack>
    """


preview = BreadcrumbSizes()

preview  # noqa: B018

Wrap or scroll long trails

Wrapping is the default. Set wrap=False for one horizontal scroll row.

Handle long Breadcrumb trails

Show code

import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class BreadcrumbOverflow(Component):
    class Kwargs:
        pass

    class Slots:
        pass

    def template_data(self, kwargs: Kwargs, slots: Slots) -> dict[str, object]:  # noqa: ARG002
        labels = ("Library", "Collections", "Natural history", "Forests", "Temperate woodland", "Field notes")
        return {
            "items": tuple(
                citry_ui.CBreadcrumbItem(label, f"/shelf/{index}")
                if index < len(labels) - 1
                else citry_ui.CBreadcrumbItem(label)
                for index, label in enumerate(labels)
            )
        }

    template = """
      <c-CStack class_="breadcrumb-overflow">
        <c-CBreadcrumbs c-items="items" label="Wrapping book location" />
        <c-CBreadcrumbs c-items="items" label="Scrolling book location" c-wrap="False" />
      </c-CStack>
    """
    css = """
      :where(.breadcrumb-overflow) {
        inline-size: min(100%, 22rem);
        padding: 1rem;
        border: 1px solid color-mix(in srgb, CanvasText 24%, transparent);
      }
    """


preview = BreadcrumbOverflow()

preview  # noqa: B018

Customize item rendering

The item slot receives the record, index, current flag, and owned native attrs. Bind attrs to preserve link and current-page semantics.

Customize Breadcrumb items

Show code

import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class BreadcrumbItemSlot(Component):
    class Kwargs:
        pass

    class Slots:
        pass

    def template_data(self, kwargs: Kwargs, slots: Slots) -> dict[str, object]:  # noqa: ARG002
        return {
            "items": (
                citry_ui.CBreadcrumbItem("Reading lists", "/lists"),
                citry_ui.CBreadcrumbItem("Summer shelf"),
            )
        }

    template = """
      <c-CBreadcrumbs c-items="items" label="Reading-list location">
        <c-fill name="item" data="{ item, index, is_current, attrs }">
          <c-if cond="item.href is not None">
            <a c-bind="attrs">
              <span aria-hidden="true">◌</span>
              {{ item.label }}
            </a>
          </c-if>
          <c-else>
            <span c-bind="attrs">
              {{ item.label }}
            </span>
          </c-else>
        </c-fill>
      </c-CBreadcrumbs>
    """


preview = BreadcrumbItemSlot()

preview  # noqa: B018

Compose route-derived records

Route integration stays outside the component. Turn your router hierarchy into CBreadcrumbItem records and pass the resulting tuple.

Compose route-derived Breadcrumbs

Show code

import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class RouteBreadcrumbs(Component):
    class Kwargs:
        pass

    class Slots:
        pass

    def template_data(self, kwargs: Kwargs, slots: Slots) -> dict[str, object]:  # noqa: ARG002
        route = (("Authors", "/authors"), ("Ursula K. Le Guin", "/authors/le-guin"), ("Books", None))
        return {"items": tuple(citry_ui.CBreadcrumbItem(label, href) for label, href in route)}

    template = '<c-CBreadcrumbs c-items="items" label="Author location" />'


preview = RouteBreadcrumbs()

preview  # noqa: B018

Customize Breadcrumbs

Override public link, current, separator, focus, and spacing variables or stable parts.

Customize Breadcrumbs with public CSS

Show code

import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class CustomBreadcrumbs(Component):
    class Kwargs:
        pass

    class Slots:
        pass

    def template_data(self, kwargs: Kwargs, slots: Slots) -> dict[str, object]:  # noqa: ARG002
        return {
            "items": (
                citry_ui.CBreadcrumbItem("Archive", "/archive"),
                citry_ui.CBreadcrumbItem("Rare books"),
            )
        }

    template = '<c-CBreadcrumbs c-items="items" label="Archive location" class_="rare-trail" separator="✦" />'
    css = """
      :where(.rare-trail) {
        --cui-breadcrumbs-link-color: light-dark(#7c2d12, #fdba74);
        --cui-breadcrumbs-current-color: light-dark(#4c1d95, #c4b5fd);
        --cui-breadcrumbs-separator-color: light-dark(#9a3412, #fb923c);
        --cui-breadcrumbs-gap: 0.8rem;
        padding: 1rem;
        border-block: 1px solid color-mix(in srgb, CanvasText 24%, transparent);
      }
    """


preview = CustomBreadcrumbs()

preview  # noqa: B018

API reference

Inputs

CBreadcrumbs server inputs

Server inputs are passed in a template through <c-CBreadcrumbs ... /> or in Python through CBreadcrumbs(...).

Input	Type	Default	Effect
`items`	`Sequence[CBreadcrumbItem]`	required	Renders a nonempty hierarchy whose final record is current.
`label`	`str`	`"Breadcrumbs"`	Names the navigation landmark.
`separator`	`str`	`"/"`	Sets hidden-from-AT visual separator fallback.
`size`	`"sm" \| "md" \| "lg"` (`CBreadcrumbsSize`)	`"md"`	Sets trail type scale.
`wrap`	`bool`	`True`	Wraps the trail; false keeps one horizontally scrollable row.
`class_`	`str \| Mapping[str, bool] \| Sequence[CClassValue] \| None` (`CClassValue`)	`None`	Adds root classes and merges them with attrs.
`style`	`str \| Mapping[str, str \| int \| float \| bool \| None] \| Sequence[CStyleValue] \| None` (`CStyleValue`)	`None`	Adds root inline styles and merges them with attrs.
`attrs`	`Mapping[str, object] \| None`	`None`	Adds copied trusted nonconflicting nav metadata.
`list_attrs`	`Mapping[str, object] \| None`	`None`	Adds copied trusted nonconflicting ordered-list metadata.

Slots

Slots are passed as nested content or <c-fill> tags in a template, or through the slots={...} argument in Python.

CBreadcrumbs slots

Slot	Required	Data	Fallback
`item`	no	`{item: CBreadcrumbItem, index: int, is_current: bool, attrs: Mapping[str, object]}` (`CBreadcrumbsItemSlotData`)	Renders the record as a native anchor or current span.
`separator`	no	`{index: int}` (`CBreadcrumbsSeparatorSlotData`)	Renders the `separator` input inside its hidden wrapper.

Events

Methods

CSS

CSS variables to theme the components. Set them on an ancestor or the component itself.

CBreadcrumbs CSS variables

Apply these variables to CBreadcrumbs or one of its ancestors.

Variable	Type	Purpose	Default
`--cui-breadcrumbs-foreground`	`color`	Root inherited foreground.	CanvasText.
`--cui-breadcrumbs-link-color`	`color`	Ancestor link color.	LinkText.
`--cui-breadcrumbs-current-color`	`color`	Current-page color.	CanvasText.
`--cui-breadcrumbs-separator-color`	`color`	Visual separator color.	Scheme-aware muted foreground.
`--cui-breadcrumbs-gap`	`length`	Item and separator spacing.	0.5rem.
`--cui-breadcrumbs-focus-color`	`color`	Link keyboard focus ring.	Highlight.

Attributes

HTML attributes defined on the components that you can refer to for CSS, inspection, and testing. Read-only.

CBreadcrumbs attributes

Attribute	Element	Type	Meaning
`aria-label`	Nav root	`nonempty string`	Names the navigation landmark.
`href`	Linked item anchor	`nonempty string`	Native ancestor or linked-current destination.
`aria-current`	Final anchor or span	`"page"`	Marks the final item as current.
`data-size`	Nav root	`"sm" \| "md" \| "lg"`	Mirrors type scale.
`data-wrap`	Nav root	`boolean present or absent`	Present while the trail wraps.

Selectors

Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.

CBreadcrumbs selectors

Selector	Element	Purpose
`[data-citry-ui-part="breadcrumbs"]`	Nav root	Landmark and root attrs destination.
`[data-citry-ui-part="list"]`	Ordered list	Trail layout and list attrs destination.
`[data-citry-ui-part="item"]`	List item	One hierarchy record.
`[data-citry-ui-part="link"]`	Native anchor	Navigable ancestor or linked current item.
`[data-citry-ui-part="current"]`	Span	Plain current-page item.
`[data-citry-ui-part="separator"]`	Hidden-from-AT span	Visual hierarchy separator.

Interfaces

Aliases and data shapes referenced above.

Input type aliases

Interface	Definition
`CClassValue`	`str \| Mapping[str, bool] \| Sequence[CClassValue]`
`CStyleValue`	`str \| Mapping[str, str \| int \| float \| bool \| None] \| Sequence[CStyleValue]`
`CBreadcrumbsSize`	`Literal["sm", "md", "lg"]`

`CBreadcrumbItem`

Field	Type	Default	Meaning
`label`	`str`	-	Visible nonempty item text.
`href`	`str \| None`	-	Native destination; None renders plain text.
`attrs`	`Mapping[str, object] \| None`	-	Copied trusted nonconflicting anchor/span attrs.

`CBreadcrumbsItemSlotData`

Field	Type	Default	Meaning
`item`	`CBreadcrumbItem`	-	Normalized item record.
`index`	`int`	-	Zero-based hierarchy position.
`is_current`	`bool`	-	True only for the final item.
`attrs`	`Mapping[str, object]`	-	Required native href/current attrs plus record attrs.

`CBreadcrumbsSeparatorSlotData`

Field	Type	Default	Meaning
`index`	`int`	-	Zero-based preceding item index.

Translation keys

Catalog keys used by this family. An explicit component input or slot listed in Override takes precedence over the catalog for that instance.

CBreadcrumbs translation keys

Key	Purpose	Variables	Override	Browser updates
`citry-ui-breadcrumbs-label`	Names the navigation landmark.	`None`	`label` input	$c-tr updates `aria-label`.