TopBar
TopBarSite header The standard site header combines branding, search, theme switching and optional account access.
Site navigation & servicesA complete header
This preview reads the same logo configuration as the site. Search is disabled inside this isolated document because it has no independent index.
Brand selection, search, navigation toggle, theme, and account access. Open the source tab to adapt the composition.
---
template: preview
index: false
title: top-bar preview
---
<TopBar :search="false" tone="neutral" variant="surface"/>
<p class="mt-4">
A complete header in its own document. The logo links home and the theme
control changes this preview.
</p> Choose the logo component
TopBar uses Regor's :is binding to render the registered component named by logoComponent. It passes the site's logo settings as config.
<TopBar logoComponent="ClassicLogo"/> For the standard documentation header, select it in siteConfig.json:
{
"logo": {
"component": "ClassicLogo",
"brand": "PureStack",
"subtitle": "AI-Native Frontend",
"icon": "tabler:device-desktop-analytics"
}
} The direct prop overrides site.logo.component; when both are omitted, TopBar renders SiteLogo. Bind a ref with :logoComponent="selectedLogo" to switch reactively. Custom registered components work too: accept a config prop and read the identity fields you need. Register the chosen component alongside TopBar when creating a standalone app.
ClassicLogo's guide includes the exact original PureStack website color configuration and all its responsive sizing options. SiteLogo provides the newer layouts and treatments.
All ten semantic tones
All supported values are visible together on the actual component, in an isolated document.
Samples follow this guide’s theme. Service appearance comparisons do not register account, search, or consent services.
All eighteen visual variants
All supported values are visible together on the actual component, in an isolated document.
Samples follow this guide’s theme. Service appearance comparisons do not register account, search, or consent services.
Feature comparisons
Each labelled sample exposes a different public feature or site configuration. Account states are presentation examples.
Configuration controls the header
The comparisons above show both logo components, explicit search visibility, and account access with an avatar. The search prop overrides site.pagefind.enabled, and signInEnabled overrides site.auth.enabled for this header.
The navigation toggle targets the doc layout’s fixed ID. Each header sample uses its own document. The working preview’s theme button switches that preview; appearance samples follow the guide’s theme.
Feature map
| Feature | Where to explore it |
|---|---|
| Brand selection, search, navigation toggle, theme, and account access | Context preview, feature comparisons, and original copyable source examples. |
| Public appearance options | Complete galleries above. Only options supported by this component are shown. |
| Native semantics and integration | Behavior notes and API contracts below explain the component’s roots, slots, and runtime dependencies. |
This component exposes tone and variant, but no variantMode.
Behavior and accessibility
Sidebar spacing below the header
When a different logo or custom header changes TopBar's height, set the sidebar offsets in siteConfig.json:
{
"docLayout": {
"sidebarTop": "5.5625rem",
"sidebarTopMobile": "4.875rem"
}
} These are the defaults. Set each value to the header height plus the clearance you want below it. sidebarTop controls the desktop navigation and table of contents, including collapsed sidebars and drawers. sidebarTopMobile controls their mobile offsets at the existing responsive breakpoints. CSS lengths such as 96px, 6rem and calc(5rem + 8px) are supported.
Both the top position and available scrolling height use the same setting. Desktop scroll panels retain their existing bottom clearance. This reserves space below the header; it does not resize TopBar itself. Rebuild the site after changing these settings.
Custom documentation templates can set --ps-doc-layout-sidebar-top and --ps-doc-layout-sidebar-top-mobile on a shared ancestor of their sidebars. The default doc template sets both from site configuration automatically.
TopBar renders a fixed doc-nav-toggle ID and should appear once per document. Its mobile navigation toggle works with the standard doc layout. Logo content comes from site.logo. Search visibility defaults to site.pagefind.enabled; the search prop overrides it.
API reference
TopBar contract
Props below are the public template API. RefOrValue accepts a literal or a reactive ref; bind refs with a colon-prefixed attribute. Native attributes and events can be passed through the component root.
logoComponent
RefOrValue<string> - Default
site.logo.component or SiteLogo
Registered component name rendered through :is. Supports SiteLogo, ClassicLogo or a custom component accepting config. A direct prop takes precedence over the site setting and can change reactively.
tone
RefOrValue<SemanticTone> - Default
inherited
Semantic intent: neutral, accent, secondary, info, success, warning, danger, feature, custom or ghost. The active skin supplies the colors.
variant
RefOrValue<ComponentVariant> - Default
surfaceAlt
Visual treatment. Accepts solid, surface, surfaceAlt, spotlight, glass, flat, flatAlt, flatSolid, outlineFill, outline, subtle, subtleBtn, link, sheen, underline, rail, bracket or none.
signInAvatarSrc
RefOrValue<string> - Default
not set
Avatar URL forwarded to SignIn when account access is shown.
signInAvatarAlt
RefOrValue<string> - Default
not set
Avatar alternative text forwarded to SignIn.
signInEnabled
RefOrValue<boolean> - Default
site.auth.enabled
Overrides site.auth.enabled for the account control in this header.
search
RefOrValue<boolean> - Default
site.pagefind.enabled
Overrides site.pagefind.enabled for this instance.
signInSignedIn
RefOrValue<boolean> - Default
runtime auth state
Forwards an explicit signed-in presentation to the account control.
Composition
Use the before-actions slot to add controls before the theme toggle, and the actions slot to add links or controls after it. Register defineTopBarComponents and the selected logo component, SearchBox, ThemeToggle, SignIn, Flex and Icon families. Standard SSG registration provides these dependencies.