Site color

Choose your site’s color palette.

Saved on this device.

TopBar

TopBarSite header

The standard site header combines branding, search, theme switching and optional account access.

Site navigation & services

A 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.

TopBar in contextCOMPOSITION

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.

All ten semantic tonesCOMPOSITION

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.

All eighteen visual variantsCOMPOSITION

Samples follow this guide’s theme. Service appearance comparisons do not register account, search, or consent services.

Feature comparisons

Every configuration in viewCOMPOSITION

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

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.

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.