---
title: Header
description: Shape the sticky top bar with site title, GitHub shortcut, theme switch, and your own CTA links.
---

Your docs site keeps the same top bar on every page. You might want the logo alone without repeating the project name, a **Sign up** button beside search, or a cleaner bar when the GitHub star count is not part of your brand story.

## Overview

The **header** is the sticky bar above page content. It holds identity on the left (logo, optional site name, branch preview badge) and actions on the right (optional Ask AI control, search, custom links, GitHub shortcut, theme toggle). When you configure [navigation tabs](/features/tabs), a second row under the main bar switches between major doc sections.

Most header behavior is controlled by the `header` object in `docs.json`. Logo images come from [`logo`](/features/logo); the site title text comes from the top-level `name` field. Search, tabs, and the agent panel are separate features. They share the header layout but are not toggled through `header`.

Field names, types, and defaults live in [docs.json](/reference/docs-json).

## How it works

### Layout and sticky behavior

The header stays fixed at the top of the viewport while readers scroll. A thin border fades in after the first scroll to separate the header from the page.

The main row is 56px tall and splits into two zones:

| Zone | Contents |
| --- | --- |
| **Left** | Home link with logo and optional site name, plus a branch or PR badge on preview URLs |
| **Right** | Optional Ask AI control, search, custom `header.links`, GitHub link to the source repository, theme toggle |

When tabs are configured, a compact tab strip appears below the main row. On small screens, a sidebar trigger sits beside the tabs so readers can open navigation without leaving the header.

### Site identity: logo and name

The home link always points to `/`. If you set `logo.light` and/or `logo.dark`, the matching image renders at 24px height and switches with the active theme. See [Logo](/features/logo) for asset paths and light/dark pairing.

The site **name** from `docs.json` appears beside the logo when both of these are true:

- `header.showName` is `true` (the default)
- `name` is set and non-empty

Set `showName` to `false` when the logo already includes your wordmark or you want a minimal bar.

### Built-in actions

Several controls always occupy the right side of the header on hosted docs sites:

- **Ask AI** appears when the agent is enabled in `docs.json`. See [Ask AI](/features/ask-ai).
- **Search** opens the command palette for full-text search across your site. See [Search](/features/search).
- **GitHub** links to `https://github.com/{owner}/{repo}` for the hosted repository and shows a formatted star count on medium and larger viewports.
- **Theme toggle** switches between light and dark mode using your [theme](/features/theme) settings.

The `header` schema also defines `showThemeToggle` and `showGitHubCard` booleans (both default to `true`). Those fields are **schema only**. Theme toggle and GitHub link always render on hosted sites today. See [docs.json: Schema-only fields](/reference/docs-json#schema-only-fields).

### Custom header links

Add outbound or in-site shortcuts with `header.links`, an array of link objects. Each entry needs `title` and `href`. Set `cta` to `true` to render a filled primary button; omit it or set `false` for an outline button.

```json
{
  "header": {
    "showName": true,
    "links": [
      {
        "title": "Changelog",
        "href": "/changelog"
      },
      {
        "title": "Get started",
        "href": "https://app.example.com/signup",
        "cta": true
      }
    ]
  }
}
```

Links render after search and before the GitHub control, in array order. Use internal paths for docs pages and full URLs for external destinations.

The schema accepts an optional `locale` string on each link so a button could appear only for a given translation. That field is **schema only**. All configured links render on every locale today. See [docs.json: Schema-only fields](/reference/docs-json#schema-only-fields).

### How header settings fit together

Header options compose with other customization without duplicating configuration:

- **Logo** supplies images; **header** decides whether the text name appears beside them.
- **Tabs** add the section switcher row; each tab still has its own sidebar tree.
- **Theme** sets colors and default mode; the header theme toggle lets readers override mode per session.
- **Social links** and Open Graph metadata affect sharing previews in the footer and meta tags, not the top bar itself. See [Social links](/features/social-links).

For a single workflow that walks through theme, logo, header, and footer together, see [Branding](/customize/branding).

## Related

<CardGroup cols={2}>
  <Card title="docs.json" icon="book" href="/reference/docs-json">
    Field lookup for `header`, `name`, `logo`, and the rest of site configuration.
  </Card>
  <Card title="Logo" icon="image" href="/features/logo">
    Light and dark logo URLs and favicons that appear in the header home link.
  </Card>
  <Card title="Theme" icon="palette" href="/features/theme">
    Presets, colors, fonts, and default light or dark mode for the site.
  </Card>
  <Card title="Navigation tabs" icon="folder" href="/features/tabs">
    Top-level tabs and the second header row that switches between them.
  </Card>
</CardGroup>