Granularity
⌘K
v1.1.1

Navigation

  • Finding the way
  • 3 min
  • components: 9
  • pairs: 3

Ten components answer three questions — where am I, where can I go, and how do I get back. Mixing them up is what makes an interface feel like a maze.

Reviewed 2026-09-05

On this page

What it solves

Navigation is three questions, always the same three: where am I, where can I go from here, and how do I get back. Every component below answers one of them, and the confusion starts when one is asked to answer two.

Tabs that change the URL are trying to be sections. Breadcrumbs on a flat site are decoration. A step indicator that lets you skip ahead is a tab strip with numbers.

Anatomy

The library states the condition for each, and the conditions divide by scope:

  1. The app has a top bar — GrNavbar. Main sections and global actions, the same on every screen.
  2. Sections are many and permanent — GrSidebar. When a top bar would run out of room, and the list is a property of the app rather than of the page.
  3. A mobile interface — GrBottomNav. Where the thumb is, for the three to five destinations that matter.
  4. Nesting is real — GrBreadcrumbs. Real, not decorative: a path that exists in the data, not a trail invented for the header.
  5. Sections with different content — GrTabs, and GrTabPanels when those sections need panels. Switching without leaving the page.
  6. Checkout or sign-up — GrSteps. A process with an order, which can hold the person back until the current step is done.
  7. The list does not fit the screen — GrPagination.
  8. Commands are many and scattered — GrCommandPalette. ⌘K over everything the app can do, for the person who already knows what they want.

Example

Do and don’t

Do — Tabs for content, routes for places

If a person can bookmark it, send it to a colleague, or expect the back button to return to it, it is a place — give it a URL. Tabs are for switching what is shown inside one place.

Don’t — Tabs that quietly change the page

A tab strip that swaps the whole screen and leaves the address unchanged breaks the back button and every link anyone tries to share. The person did navigate; only the browser was not told.

Do — Steps that hold, tabs that cycle

GrTabs cycles with arrows, Home and End — it is a composite widget of choice. GrSteps deliberately has no arrow ring: it is navigation through a process, each reachable step is its own Tab stop, and unreachable ones are not reachable for a reason.

Don’t — A step indicator you can jump around in

If any step opens at any time, the order was never real, and the indicator is a tab strip with numbers. Either the process has an order — and then it holds — or it does not, and then it is sections.

Do — Breadcrumbs when the path exists

GrBreadcrumbs shows where the person is inside a hierarchy that is really there — a catalogue, a file tree, a set of nested settings.

Don’t — Breadcrumbs on a flat site

«Home / Pricing» tells nobody anything: there was no path, and the row is a decoration that takes a line and offers a click that goes where the logo already goes.

Accessibility

A tab strip is a keyboard pattern, not a row of buttons. Arrows move between tabs and cycle; Home and End jump to the ends; the strip is one Tab stop, not one per tab. GrTabs implements this, and GrTabPanels ties the panels to their tabs by ARIA so the announcement matches what is shown.

Steps are not that pattern, on purpose. They are links through a process, so each available step is its own Tab stop. Giving them an arrow ring would announce a widget of choice where there is a sequence.

«You are here» must be said, not only drawn. The current section in a navbar, the current page in pagination, the current step — a bolder colour is invisible to a screen reader, and to anyone who cannot see the difference between two shades of the same hue.

The command palette is the exception that proves the rule: it is a shortcut for people who already know the way, and it never replaces the visible path for people who do not.

Components in this pattern

The list is built from frontmatter, not from links in the prose: renaming a slug does not lose it.

Keyboard

Contracts come from the library. The pattern does not restate them — it points at them.