# Topbar

The 40px sticky bar at the top of the shell. Left to right: the brand
cluster, the merged breadcrumb, the [TabStrip](#tabstrip), the search
field, and the actions cluster (GitHub link, dev-mode dot, theme
toggle).

## Anatomy

```text
┌─ 40px, sticky ──────────────────────────────────────────────────────┐
│ brand. subtitle [pkg|v0.2.0 ▾] [a1b2c3]  ┊crumb┊  TABS  [⌘K ⌕]  ○ ◐ │
│ └───────── brand cluster ─────────────┘           tabs   search  actions
└─────────────────────────────────────────────────────────────────────┘
   crumb = merged breadcrumb, fades in when the H1 scrolls under the bar
```

## Props

The [Layout](/reference/components/shell.md) owns the search state and passes it
down; you only touch these props in a custom shell:

| Prop | Meaning |
| --- | --- |
| `searchOpen` | Whether the palette is open (drives the field's FLIP). |
| `onOpenSearch` / `onCloseSearch` | Open/close callbacks, also bound to **⌘K** and **/**. |
| `query` / `setQuery` | The live search string, shared with the [SearchPalette](/guides/search.md). |

Everything else — brand, chips, tabs, links — comes from `siteConfig`
and the `TABS` registry.

## Brand cluster

`{brand}. / {subtitle}` renders from `siteConfig`, followed by any
**version chips** and the **git hash chip**:

```ts file="site.config.ts"
initDocs({
  site: {
    brand: 'DreamLake',
    subtitle: 'Dockit',
    versionChips: [{ label: 'dockit', version: __DOCKIT_VERSION__,
                     dropdown: true, manifestUrl: '/dockit-versions.json' }],
    gitHash: __GIT_HASH__,
  },
  // …
})
```

The chip values are the consumer's business — this site injects them
via Vite `define` from the workspace package.json and
`git rev-parse --short=6 HEAD` (see
[Releases & versioning](/guides/releases.md) for the full pattern).

- A chip with `dropdown: true` becomes the **version switcher**: it
  fetches its `manifestUrl` (default `/versions.json`) and lists aliases + past deploys in a
  keyboard-dismissable popover. These and every other badge in the
  shell share one visual idiom — see [Chip](/reference/components/chip.md) for the
  spec and all the ways to inject badges.
- On version-subdomain deploys (`v0-1-0.…`), the chip re-labels itself
  from `window.location.hostname` after hydration. A custom product
  manifest must contain that version before the hostname can override
  the label; this prevents a docs-build version from relabeling a product badge.
- Chips can be **scoped per tab**: a `TabDef.versionChips` array
  overrides `site.versionChips` while that tab is active (omit to
  inherit, `[]` to show none). Handy for showing a cli-only chip on the
  CLI tab and none on a design tab — see
  [Site config](/guides/site-config.md#scoping-chips-per-tab).
- `prefix` defaults to `v`; use `prefix: ''` for revision labels. This
  site's Python tab shows `main` plus its source revision without a
  dropdown, while Dockit's badge uses `/dockit-versions.json`.
- `gitHash` unset (empty) hides the hash chip entirely.

## Breadcrumb merge

Scroll this page: once the H1 passes under the bar, the brand cluster
collapses and a `Doc Kit / Shell / Topbar` breadcrumb fades in —
the merge state from the [Layout](/reference/components/shell.md), read via
`useMerge()`. `breadcrumbRoot` in `siteConfig` supplies the leftmost
crumb; empty string omits it.

## TabStrip

The compact tab cluster on the topbar's right side: uppercase mono
labels with a sliding ink underbar that tracks the active (or hovered)
tab. You can see it live at the top of this page — the **Reference**
tab is active right now. `` renders inline inside the
topbar; it carries no sticky/blur/background of its own, and takes no
props — all input comes from the `TABS` registry and the current URL
via Vike's page context.

### Data source

The strip renders the `TABS` registry, populated by `initDocs({ tabs })`
(or `initTabs()` directly). Each tab is a `TabDef`:

```ts
export interface TabDef {
  id: string        // stable key, e.g. 'components'
  label: string     // strip label, e.g. 'Components'
  numeral: string   // editorial chapter numeral, e.g. 'II'
  landing: string   // where clicking the tab navigates
  urlPrefix: string // pages under this prefix belong to the tab
}
```

This site's registry, for reference:

```ts file="site.config.ts"
tabs: [
  { id: 'dockit', label: 'Dockit', numeral: 'I',
    landing: '/', urlPrefix: '/get-started' },
  { id: 'reference', label: 'Reference', numeral: 'II',
    landing: '/reference/config', urlPrefix: '/reference' },
  { id: 'python-autodoc', label: 'Python Autodoc', numeral: 'III',
    landing: '/python-autodoc', urlPrefix: '/python-autodoc' },
]
```

### Behavior

- The active tab derives from the URL's first path segment
  (`tabForUrl`). `/` and unknown prefixes resolve to the first tab, so
  orphan pages never empty the sidebar.
- The [Sidebar](/reference/components/shell.md#sidebar) filters its groups to the active
  tab's pages — tabs are a lens, not separate sites. One tab can carry
  several sidebar sections: on this site the **Reference** tab
  (`urlPrefix: '/reference'`) holds *API*, *Shell*, and *Content components* groups.
- The underbar tracks the **hovered** tab while the pointer is over the
  strip (measured with `useLayoutEffect` against live DOM rects, so it
  survives window resizes), then springs back to the active tab.
- **Empty registry:** with no tabs (`tabs: []` or omitted), the strip
  renders nothing and the sidebar shows every section.

## Search field

The field is a FLIP-animated fixed element: closed, it sits at the
grid's right; open (**⌘K** — **Ctrl+K** on non-Mac — or **/**), it
expands into the palette input. The animation measures the closed rect
after each paint, so window resizes stay smooth. Below `lg` it
collapses to an icon button.

## Actions cluster

- **GitHub link** — `siteConfig.repoUrl` drives the icon; empty string
  hides it.
- **DEV badge** — a warn-variant [Chip](/reference/components/chip.md) reading
  `DEV` appears while hidden pages are revealed (**Cmd+Shift+D**);
  clicking it turns the toggle back off.
  See [Sidebar](/reference/components/shell.md#sidebar) for what the toggle reveals.
- **Theme toggle** — light/dark/system; see [Theming](/guides/theming.md).

## Related siteConfig fields

| Field | Drives |
| --- | --- |
| `brand`, `subtitle` | The brand cluster text. |
| `versionChips`, `gitHash` | The chips after the brand. |
| `breadcrumbRoot` | The leftmost merged-breadcrumb crumb. |
| `repoUrl` | The GitHub icon link. |