---
title: Subdomain nav bar
description: Use the subdomain nav bar component for top level navigation for subdomain sites.
keywords: ['navigation', 'top level']
ready: true
figma: https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=1024%3A32796
source: https://github.com/primer/brand/blob/main/packages/react/src/SubdomainNavBar/SubdomainNavBar.tsx
storybook: '/brand/storybook/?path=/story/components-subdomainnavbar--playground'
---

```js
import {SubdomainNavBar} from '@primer/react-brand'
```

## Examples

> `SubdomainNavBar` is designed to fix to the top of the viewport.
>
> Please refer to our Storybook examples to see the component in a full-screen browser as originally intended.

### Basic

```jsx
<div style={{width: '100%'}}>
  <SubdomainNavBar title="Subdomain" fixed={false}>
    <SubdomainNavBar.Link href="#">Collections</SubdomainNavBar.Link>
    <SubdomainNavBar.Link href="#">Topics</SubdomainNavBar.Link>
    <SubdomainNavBar.Link href="#">Social</SubdomainNavBar.Link>
    <SubdomainNavBar.PrimaryAction href="#">Primary CTA</SubdomainNavBar.PrimaryAction>
    <SubdomainNavBar.SecondaryAction href="#">Secondary CTA</SubdomainNavBar.SecondaryAction>
  </SubdomainNavBar>
</div>
```

### Featured variant

The `featured` variant displays the GitHub name alongside the site title and an expanded search field on desktop.

> This variant is for internal use only.
>
> Please check with the Primer Brand team before using this variant.

```jsx
<div style={{width: '100%'}}>
  <SubdomainNavBar title="Site title" variant="featured" fixed={false} fullWidth>
    <SubdomainNavBar.Link href="#">Overview</SubdomainNavBar.Link>
    <SubdomainNavBar.Link href="#">Documentation</SubdomainNavBar.Link>
    <SubdomainNavBar.Link href="#">Resources</SubdomainNavBar.Link>
    <SubdomainNavBar.Search
      placeholder="Search Site title"
      searchTerm=""
      searchResults={[]}
      onChange={() => undefined}
      onSubmit={event => event.preventDefault()}
    />
    <SubdomainNavBar.PrimaryAction href="#">Primary CTA</SubdomainNavBar.PrimaryAction>
  </SubdomainNavBar>
</div>
```

### Search

`SubdomainNavBar` offers an optional search form control that supports both `onSubmit` and `onChange`; use `onChange` to display inline results. The `placeholder` labels the input in the opened dialog and defaults to `Search {title}`, or `Search` when no navigation title is available.

Keyboard shortcuts are disabled by default. Pass `keyboardShortcut`, such as `keyboardShortcut="/"`, to opt into a global shortcut that opens the search dialog. For programmatic control with `openSearch()` and `closeSearch()`, see the Imperative Search API Storybook example.

```jsx filename="noinline"
const groupedResults = [
  {
    title: 'Recommended',
    results: [
      {
        title: 'Getting started with GitHub',
        description: 'Create an account and learn the basics.',
        url: '/en/get-started',
        date: '2026-07-01',
        category: 'Guide',
      },
    ],
  },
  {
    title: 'API reference',
    results: [
      {
        title: 'REST API documentation',
        description: 'Integrate with GitHub using the REST API.',
        url: 'https://docs.github.com/en/rest',
        date: '2026-07-01',
        category: 'Reference',
        isExternal: true,
      },
    ],
  },
]

const SearchNav = () => {
  const [searchTerm, setSearchTerm] = React.useState('')

  return (
    <div style={{width: '100%'}}>
      <SubdomainNavBar title="GitHub Docs" fixed={false} fullWidth>
        <SubdomainNavBar.Link href="/en/get-started">Get started</SubdomainNavBar.Link>
        <SubdomainNavBar.Search
          placeholder="Search GitHub Docs"
          keyboardShortcut="/"
          searchTerm={searchTerm}
          searchResults={searchTerm ? groupedResults : []}
          onChange={event => setSearchTerm(event.currentTarget.value)}
          onSubmit={event => {
            event.preventDefault()
          }}
        />
      </SubdomainNavBar>
    </div>
  )
}

render(<SearchNav />)
```

Search results can be a flat list or grouped by title. Do not mix both formats in the same array.

### Localized search

Use the `labels` prop to localize search text. Any labels you omit fall back to English.

```jsx filename="noinline"
const searchProps = {
  searchLabel: 'Buscar',
  closeLabel: 'Cerrar',
  resultsLabel: 'Resultados',
  searchResultsLabel: 'Resultados de búsqueda',
  formatSearchWithTitle: title => `Buscar en ${title}`,
  formatSearchTrigger: placeholder => `Abrir ${placeholder}`,
  formatResultsHeading: searchTerm => `Resultados para «${searchTerm}»`,
  formatResultsLabel: searchTerm => `Resultados para ${searchTerm}`,
  formatSuggestions: count => `${count} sugerencia${count === 1 ? '' : 's'}.`,
  placeholder: 'Buscar documentación',
}

const LocalizedSearch = () => {
  const [searchTerm, setSearchTerm] = React.useState('')

  return (
    <div style={{width: '100%'}}>
      <SubdomainNavBar title="Documentación" fixed={false}>
        <SubdomainNavBar.Search
          {...searchProps}
          searchTerm={searchTerm}
          onChange={event => setSearchTerm(event.currentTarget.value)}
          onSubmit={event => event.preventDefault()}
        />
      </SubdomainNavBar>
    </div>
  )
}

render(<LocalizedSearch />)
```

### Localized menu controls

Use `menuLabels` to localize the narrow menu control and desktop overflow menu. The narrow menu label changes when the menu opens, and any omitted value falls back to English.

```jsx filename="noinline"
const LocalizedMenu = () => (
  <div style={{width: '100%'}}>
    <SubdomainNavBar
      title="Documentación"
      fixed={false}
      menuLabels={{
        menuLabel: 'Menú',
        closeLabel: 'Cerrar',
        overflowMenuLabel: 'Más',
      }}
    >
      <SubdomainNavBar.Link href="/es/get-started">Primeros pasos</SubdomainNavBar.Link>
      <SubdomainNavBar.PrimaryAction href="/es/signup">Registrarse</SubdomainNavBar.PrimaryAction>
    </SubdomainNavBar>
  </div>
)

render(<LocalizedMenu />)
```

## Accessibility

- Render `SubdomainNavBar` before other focusable page content so its skip-to-content link is the first keyboard-accessible control.
- Provide a concise, meaningful `title`. It labels the navigation and communicates the subdomain to assistive technologies.
- Set `skipToContentTargetId` to the ID of the page's active main content element. Activating the skip link moves focus to that element and clears the fixed navigation bar. When omitted, or if the explicit target is unavailable, the component targets the first rendered `main` that is not hidden from assistive technologies.
- When the menu opens on narrow viewports, hide the rest of the document from screen readers with `inert` or `aria-hidden="true"`. Use `onNarrowMenuToggle` to track the menu state.
- Localize the menu controls' visible and accessible labels with `menuLabels`.
- Only opt into a `keyboardShortcut` that does not conflict with browser, operating system, or application shortcuts. Always provide another visible way to open search.
- For search, localize its visible text, accessible labels, result headings, and live-region announcements. Supplying only some `labels` values produces a mix of localized text and English defaults.

## Component props

### SubdomainNavBar `Required`

| Name                    | Type                                                                                                                                                 | Default              | Description                                                             |
| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- | :---------------------------------------------------------------------- |
| `children`              | `'SubdomainNavBar.Link' \| 'SubdomainNavBar.Search' \| 'SubdomainNavBar.PrimaryAction' \| 'SubdomainNavBar.SecondaryAction' \| 'React.ReactElement'` |                      | Valid child nodes                                                       |
| `className`             | `string`                                                                                                                                             |                      | Sets a custom class on the root element                                 |
| `id`                    | `string`                                                                                                                                             |                      | Sets a custom ID on the root element                                    |
| `style`                 | `React.CSSProperties`                                                                                                                                |                      | Forwards custom inline styles to the root element                       |
| `fixed`                 | `boolean`                                                                                                                                            | `true`               | Fixes the navigation bar to the top of the viewport                     |
| `fullWidth`             | `boolean`                                                                                                                                            | `false`              | Allows the inner content to fill the available width                    |
| `variant`               | `'default' \| 'featured'`                                                                                                                            | `'default'`          | Sets the navigation layout                                              |
| `logoHref`              | `string`                                                                                                                                             | `https://github.com` | Changes the URL of the GitHub logo                                      |
| `title`                 | `string`                                                                                                                                             |                      | Required subdomain name used visibly and by assistive technologies      |
| `titleHref`             | `string`                                                                                                                                             | `/`                  | Links the title to the subdomain root                                   |
| `menuLabels`            | `Partial<SubdomainNavBarMenuLabels>`                                                                                                                 | English labels       | Overrides the menu controls' visible and accessible labels              |
| `skipToContentTargetId` | `string`                                                                                                                                             | First visible `main` | ID of the element focused by the skip-to-content link                   |
| `ref`                   | `React.Ref<SubdomainNavBarHandle>`                                                                                                                   |                      | Ref to the root element with `openSearch()` and `closeSearch()` methods |
| `onNarrowMenuToggle`    | `(isOpen: boolean) => void`                                                                                                                          |                      | Called with the new state when the narrow menu opens or closes          |

`SubdomainNavBarProps`, `SubdomainNavBarHandle`, `SubdomainNavBarMenuLabels`, and `SubdomainNavBarVariant` are exported from `@primer/react-brand`.

### Menu labels

| Field               | Type     | English default | Purpose                                                      |
| :------------------ | :------- | :-------------- | :----------------------------------------------------------- |
| `menuLabel`         | `string` | `Menu`          | Visible and accessible label while the narrow menu is closed |
| `closeLabel`        | `string` | `Close`         | Visible and accessible label while the narrow menu is open   |
| `overflowMenuLabel` | `string` | `More`          | Visible and accessible label for the desktop overflow menu   |

### SubdomainNavBar.Search

| Name               | Type                                             | Default          | Description                                                           |
| :----------------- | :----------------------------------------------- | :--------------- | :-------------------------------------------------------------------- |
| `onSubmit`         | `(event: FormEvent<HTMLFormElement>) => void`    |                  | Required search form submit handler                                   |
| `onChange`         | `(event: ChangeEvent<HTMLInputElement>) => void` |                  | Required search input change handler                                  |
| `placeholder`      | `string`                                         | `Search {title}` | Text shown in the input trigger and opened search input               |
| `shortcutLabel`    | `string`                                         | Shortcut value   | Visible input-trigger hint; pass an empty string to hide it           |
| `keyboardShortcut` | `string \| false`                                |                  | Optional global key or modifier combination that opens search         |
| `labels`           | `Partial<SubdomainNavBarSearchLabels>`           | English labels   | Overrides visible and accessible search text and formatting functions |
| `searchResults`    | `SubdomainNavBarSearchResults`                   |                  | Flat or explicitly grouped results                                    |
| `searchTerm`       | `string`                                         |                  | Current query used in result headings and accessible labels           |
| `className`        | `string`                                         |                  | Sets a custom class on the search trigger container                   |
| `ref`              | `React.Ref<HTMLInputElement>`                    |                  | Ref to the input inside the opened search dialog                      |

`SubdomainNavBarSearchProps` and `SubdomainNavBarSearchLabels` are exported from `@primer/react-brand`.

### Search labels

| Field                   | Type                              | English default               | Purpose                                                  |
| :---------------------- | :-------------------------------- | :---------------------------- | :------------------------------------------------------- |
| `searchLabel`           | `string`                          | `Search`                      | Accessible label for the search input                    |
| `closeLabel`            | `string`                          | `Close`                       | Visible and accessible close action                      |
| `resultsLabel`          | `string`                          | `Results`                     | Accessible label for an untitled result group            |
| `searchResultsLabel`    | `string`                          | `Search results`              | Accessible label for grouped results without a query     |
| `formatSearchWithTitle` | `(title: string) => string`       | `Search ${title}`             | Formats the default placeholder and dialog label         |
| `formatSearchTrigger`   | `(placeholder: string) => string` | `${placeholder} search`       | Formats the responsive search trigger's accessible label |
| `formatResultsHeading`  | `(searchTerm: string) => string`  | `Results for “${searchTerm}”` | Formats the visible heading for ungrouped results        |
| `formatResultsLabel`    | `(searchTerm: string) => string`  | `Results for ${searchTerm}`   | Formats the accessible label for grouped results         |
| `formatSuggestions`     | `(count: number) => string`       | `${count} suggestions.`       | Formats the polite live-region result-count announcement |

### Search result types

`SubdomainNavBarSearchResultProps`, `SubdomainNavBarSearchResultGroupProps`, and `SubdomainNavBarSearchResults` are exported from `@primer/react-brand`.

#### `SubdomainNavBarSearchResultProps`

| Field         | Type      | Required | Description                                                              |
| :------------ | :-------- | :------: | :----------------------------------------------------------------------- |
| `title`       | `string`  |    Yes   | Linked result title                                                      |
| `description` | `string`  |    Yes   | Result summary                                                           |
| `url`         | `string`  |    Yes   | Link destination                                                         |
| `date`        | `string`  |    Yes   | Displayed date string; format it for the user's locale before passing it |
| `category`    | `string`  |          | Optional metadata displayed after the date                               |
| `group`       | `string`  |          | Groups flat results under a shared heading                               |
| `isExternal`  | `boolean` |          | Shows an external-link indicator for grouped results                     |

#### `SubdomainNavBarSearchResultGroupProps`

| Field     | Type                                 | Required | Description                       |
| :-------- | :----------------------------------- | :------: | :-------------------------------- |
| `title`   | `string`                             |    Yes   | Visible and accessible group name |
| `results` | `SubdomainNavBarSearchResultProps[]` |    Yes   | Results in the group              |

### SubdomainNavBar.Link `Required`

`SubdomainNavBar.Link` renders an anchor link.

| Name         | Type              | Default | Description                                              |
| :----------- | :---------------- | :-----: | :------------------------------------------------------- |
| `children`   | `React.ReactNode` |         | Link content                                             |
| `className`  | `string`          |         | Applies a custom class                                   |
| `href`       | `string`          |         | Destination path for the anchor element                  |
| `isExternal` | `boolean`         | `false` | Renders an external-link icon after the link when `true` |
| `rel`        | `string`          |         | Sets the relationship between the current page and link  |
| `target`     | `string`          |         | Sets where the linked document opens                     |

The `target` and `rel` props are passed to the rendered anchor. Other additional props are passed to the wrapping `<li>` element.