{"slug":"breadcrumbs","meta":{"title":"Breadcrumbs","slug":"breadcrumbs","kind":"pattern","summary":"A trail showing where the current screen sits in the hierarchy, with every ancestor clickable — the answer to \"how did I get here\" that survives a deep link.","problem":"Someone opens a record from a link, a search result or a bookmark. They can see the record but not what contains it, so they cannot get to the sibling they actually wanted, and the browser Back button leads somewhere unrelated.","family":["orient","find"],"data_shape":["record","hierarchy"],"principles":["orientation"],"interaction":["navigation"],"density":"low","complexity":"low","status":"stable","visibility":"public","use_when":["The data is genuinely hierarchical — project contains milestone contains task.","People arrive at inner pages directly, not only by drilling down.","Moving up a level is a real thing people want to do."],"avoid_when":["The structure is flat. A breadcrumb of one item is decoration.","The trail would just repeat the navigation bar's current item.","The path is a filter or a search, not a containment. That is a back link, not a breadcrumb."],"alternatives":[{"slug":"persistent-navigation","when":"You need \"where can I go\" rather than \"what contains this\"."},{"slug":"back-link","when":"There is exactly one place to return to and no hierarchy above it."}],"ask_leo":"Add breadcrumbs to the record pages in this hierarchy.\n\n- Show the containment path from the root to the current record, with a clear\n  separator between levels.\n- Every ancestor is a link. The current item is the last crumb and is NOT a\n  link — it is where you are.\n- Build the trail from the record's actual parents, not from the browser\n  history. A breadcrumb must be identical whether the person drilled down or\n  opened a bookmark.\n- Use the names people say out loud, not ids.\n- If a level's name is long, truncate the middle of that crumb rather than\n  wrapping the trail onto a second line.\n- On a narrow screen, collapse the middle levels to a single overflow crumb\n  but always keep the root and the immediate parent visible.\n","related":[{"title":"Orientation","url":"/patterns/orientation","summary":"The principle — where am I, how did I get here, where can I go next."}]},"body":"## Anatomy\n\n```\nProjects  ›  Riverside Fit-Out  ›  Phase 2 — Framing  ›  Task 118\n────────     ─────────────────     ──────────────────     ────────\n link            link                    link             current,\n                                                          not a link\n```\n\nThe rules that make it work rather than decorate:\n\n- **It reflects containment, not history.** History is per-visit and cannot be\n  linked to; containment is a property of the record and is the same for\n  everyone. A \"breadcrumb\" built from where the user came from is a back\n  button wearing a costume.\n- **The last crumb is not a link.** A link to the page you are on teaches people\n  the trail is unreliable.\n- **Ancestors are real targets.** The value is jumping two levels up in one\n  click — that is the whole point.\n\n## Why it works\n\nIt answers *how did I get here* for someone who did not get here any particular\nway. That is the case a navigation bar cannot serve: nav tells you the sections\nof the product, breadcrumbs tell you where this specific record lives inside one.\n\nIt also converts the most common recovery action — \"I want the sibling of this\nthing\" — from a navigate-search-filter sequence into one click on the parent.\n\n## Getting it wrong\n\n- **A trail that is really a back button.** Different for each visitor, wrong\n  after a bookmark.\n- **Ids instead of names.** `Projects › 4471 › 88 › 118` orients nobody.\n- **Wrapping to two lines** on long names, which makes the trail louder than the\n  page title beneath it.\n- **Breadcrumbs on a flat app**, where every trail is `Home › Thing` and the\n  pattern is pure ceremony.\n\n## Exemplars\n\n**GitHub** puts the trail in the page header for files —\n`org / repo / src / models / user.rb` — and every segment is a real, useful\ndestination. It is the clearest demonstration that a breadcrumb's value is\nproportional to how much you want to visit the ancestors.\n\n**Google Drive** shows the same trail doing double duty as the drop target for\nmoving a file up a level, which is what happens when a breadcrumb is genuinely\nthe structure rather than a label of it.\n\nThe extractable rule: **a breadcrumb is only worth its space if the ancestors\nare places worth going.** If nobody ever clicks the middle crumb, the hierarchy\nit displays is not the hierarchy people think in.\n"}