Breadcrumb

Shows the path to the current page as a trail of links.

Installation

Included in poetry-ui — available as poetry_breadcrumb the moment you've installed Poetry, with no per-component step. To own the source and edit it, copy it into your app:

bin/rails g poetry:add breadcrumb

Default

<%= poetry_breadcrumb do |crumb| %>
  <% crumb.with_item("Home", href: "#") %>
  <% crumb.with_item("Components", href: "#") %>
  <% crumb.with_item("Breadcrumb") %>
<% end %>

Collapsed

<%= poetry_breadcrumb do |crumb| %>
  <% crumb.with_item("Home", href: "#") %>
  <% crumb.with_ellipsis %>
  <% crumb.with_item("Components", href: "#") %>
  <% crumb.with_item("Breadcrumb") %>
<% end %>

Custom separator

<%# with_separator swaps the chevron in EVERY gap - an icon name, or a
    block for arbitrary content. The default chevron RTL-flips; a custom
    glyph is used exactly as given. %>
<%= poetry_breadcrumb do |crumb| %>
  <% crumb.with_separator(icon: :dot) %>
  <% crumb.with_item("Home", href: "#custom-separator") %>
  <% crumb.with_item("Components", href: "#custom-separator") %>
  <% crumb.with_item("Breadcrumb") %>
<% end %>

<%# A middle crumb can BE a dropdown: a block item hands the <li> to your
    content, and the ghost trigger is restyled to read as breadcrumb text
    (h-auto p-0, muted, no hover surface). Dot separators keep the trail
    quiet around the interactive crumb - the two features compose. %>
<%= poetry_breadcrumb do |crumb| %>
  <% crumb.with_separator(icon: :dot) %>
  <% crumb.with_item("Home", href: "#dropdown") %>
  <% crumb.with_item do %>
    <%= poetry_dropdown_menu(align: :start) do |menu| %>
      <% menu.with_trigger(variant: :ghost, size: :sm,
                           class: "h-auto gap-1 p-0 font-normal text-muted-foreground hover:bg-transparent hover:text-foreground") do %>
        Components
        <%= poetry_icon(name: :"chevron-down", class: "size-3.5") %>
      <% end %>
      <% menu.with_group do |group| %>
        <% group.with_item { "Documentation" } %>
        <% group.with_item { "Themes" } %>
        <% group.with_item { "GitHub" } %>
      <% end %>
    <% end %>
  <% end %>
  <% crumb.with_item("Breadcrumb") %>
<% end %>

Link component

<%# Upstream's "link component" section swaps the framework router's <Link>
    into a crumb; in Rails every <a> is already Turbo-driven, so
    with_item(href:) IS the router link. Reach for a block item when the
    anchor needs your own helper - link_to with Turbo options, extra data
    attributes - and style it as a crumb with two utilities. %>
<%= poetry_breadcrumb do |crumb| %>
  <% crumb.with_item do %>
    <%= link_to "Home", "#link-component", class: "transition-colors hover:text-foreground" %>
  <% end %>
  <% crumb.with_item do %>
    <%= link_to "Components", "#link-component", class: "transition-colors hover:text-foreground",
                data: { turbo_prefetch: false } %>
  <% end %>
  <% crumb.with_item("Breadcrumb") %>
<% end %>

API

Poetry::Ui::Breadcrumb::Component — options are constructor keywords (the poetry_* helper forwards them); slots are composed inside the block. Generated from the gem's source documentation.

Slots

Writer	Description
with_item	The crumbs, in declaration order. A label with href: renders a link; without one, the current page. A block makes the <li>'s content caller-owned (a dropdown crumb, a custom-rendered link).
with_separator	Replaces the separator glyph in EVERY gap: an icon name, or a block for arbitrary content. Absent, the default chevron renders (with its RTL flip - a custom glyph is used as given).

Methods

Method	Description
#with_ellipsis	Adds a collapsed-middle marker to the trail; screen readers hear "More".

Styling

Every part carries a stable data-slot attribute — target [data-slot=…] from your own CSS to restyle it. State rides data attributes on the parts below. This contract is verified against rendered DOM in CI.

Part	Description
[data-slot=breadcrumb]	The <nav> landmark (aria-label=breadcrumb) around the trail
[data-slot=breadcrumb-list]	The <ol> laying crumbs and separators out as one wrapping row
[data-slot=breadcrumb-item]	One <li> of the trail - wraps a link, the current page, the ellipsis, or a block item's own content (a dropdown crumb, a custom link)
[data-slot=breadcrumb-link]	A crumb with href: - a real <a> to an ancestor page
[data-slot=breadcrumb-page]	The current page (the item without href:) - aria-current=page, not a link
[data-slot=breadcrumb-separator]	The chevron <li> between crumbs - presentational, aria-hidden
[data-slot=breadcrumb-ellipsis]	The collapsed-middle glyph (with_ellipsis) - aria-hidden; a sibling sr-only 'More' announces it