Skip to main content

Subdomain nav bar

Use the subdomain nav bar component for top level navigation for subdomain sites.

Ready to use


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

Loading

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.

Loading

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.

Loading

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.

Loading

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.

Loading

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.

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`

Additional props are passed to the wrapping <li> element. See MDN for accepted list item attributes.