Topbar
The 40px sticky bar at the top of the shell. Left to right: the brand cluster, the merged breadcrumb, the TabStrip, the search field, and the actions cluster (GitHub link, dev-mode dot, theme toggle).
Anatomy
Props
The Layout 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. |
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:
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 for the full pattern).
- A chip with
dropdown: truebecomes the version switcher: it fetches itsmanifestUrl(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 for the spec and all the ways to inject badges. - On version-subdomain deploys (
v0-1-0.…), the chip re-labels itself fromwindow.location.hostnameafter 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.versionChipsarray overridessite.versionChipswhile 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. prefixdefaults tov; useprefix: ''for revision labels. This site's Python tab showsmainplus its source revision without a dropdown, while Dockit's badge uses/dockit-versions.json.gitHashis shown only in dev mode; unset (empty) hides it entirely.
Breadcrumb merge
Scroll this page: once the H1 passes under the bar, the subtitle and version chips collapse and the page breadcrumb fades in beside the wordmark. On sites with tabs, the wordmark replaces the root crumb: DreamLake. / Guides / Envs. The remaining path fits between the wordmark and the tabs, with long page titles truncated to avoid overlap.
The merge state comes from Layout, read via
useMerge(). On sites without tabs, breadcrumbRoot supplies the leftmost
text crumb; an empty string omits it. Below the desktop breadcrumb breakpoint,
the page-top breadcrumb remains the source of page context.
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. <TabStrip> 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:
This site's registry, for reference:
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 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
useLayoutEffectagainst 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 — visible only in dev mode.
siteConfig.repoUrldrives the icon; empty string hides it. - DEV badge — a warn-variant Chip reading
DEVappears while hidden pages are revealed (Cmd+Shift+D); clicking it turns the toggle back off. See Sidebar for what the toggle reveals. - Theme toggle — light/dark/system; see Theming.
Related siteConfig fields
| Field | Drives |
|---|---|
brand, subtitle | The brand cluster text. |
versionChips, gitHash | The chips after the brand. |
breadcrumbRoot | The leftmost merged-breadcrumb crumb on sites without tabs. |
repoUrl | The GitHub icon link. |