Header

Examples

Signed out

View va-header-navigation in Storybook

Signed in

View va-header-navigation signed in in Storybook

Signed in with limited access

View va-header-navigation signed in with limited access in Storybook

Usage

When to use Header

• At the top of every VA.gov page. The header gives people global navigation, search, and a way to sign in or reach their account from anywhere on VA.gov.

When to consider something else

• In a form flow or other task where leaving would cause problems. Use Header - Minimal when navigating away could cause people to lose their progress or abandon their task.
• For navigating within a section of VA.gov. In addition to the Header, use Side Navigation to move between related pages in a section.
• For page-level actions or titles. Put these in the page content, not the header.

How this component works

The header is a single, compact bar. From top to bottom, the top of every VA.gov page has 3 parts:

1. Banner - Official Gov. This component is required for all U.S. government websites. It isn’t part of the Header component.
2. Crisis Line Modal. The Veterans Crisis Line button opens a modal window. It isn’t part of the Header component.
3. Header. The va-header-navigation bar holds these parts:
   • VA logo. The logo links to the VA.gov home page. When a person is signed in, the logo links to My VA.
   • Main navigation. The main navigation lists the top-level sections of VA.gov, ending with Contact us. A section with subsections opens a panel. A section without subsections is a plain link.
   • Search link. A link to the VA.gov search page. The header doesn’t include a search input.
   • Sign in button or Menu button. People who are signed out (unauthenticated) see a Sign in button. People who are signed in (authenticated) see a Menu button that holds both their account links and the main navigation.

The header includes the full VA.gov navigation, so teams don’t need to supply navigation data.

Behavior

Navigation panels

• Panels open on click, not on hover. Selecting a top-level section opens its panel below the bar. Selecting it again closes the panel.
• Only 1 panel or menu is open at a time. Opening a panel closes any other open panel or menu.
• Panels close when people move on. Pressing Escape, clicking outside the header, moving keyboard focus out of the panel, or selecting a link closes the panel.
• Benefit hub panels always show 1 hub’s links. A list of benefit hubs sits at the leading edge of the panel. Selecting a hub replaces the links beside it. Selecting the hub that’s already showing does nothing, so the panel is never empty.

Signed-in and signed-out menus

These are also called the authenticated and unauthenticated menus.

• One menu holds the main navigation and account links when a person is signed in. A Menu button appears in the header at every width, in the same place the Sign in button appears when signed out. There’s no separate account button. At the vads-breakpoint-tablet-lg breakpoint, there isn’t room for 2 menus, and one consistent menu avoids navigation problems.
• The menu opens with a “Welcome” heading that names the person who is signed in. This shows who is signed in. If the name isn’t available, the heading reads “Welcome” without a name.
• The menu has My VA and Profile sections, and Sign out comes last. The My VA section includes links to My VA and My HealtheVet. Without these links, people on a page without a side navigation had no way back to My VA. At vads-breakpoint-tablet-lg and wider, My VA and Profile appear side by side. Below vads-breakpoint-tablet-lg, the sections stack and a “More on VA.gov” section adds the main navigation links that no longer fit in the header.
• The My VA section matches the links in the compact variant of Side Navigation. Below vads-breakpoint-tablet-lg, the side navigation isn’t shown, so those links are available only in the menu. Read Side Navigation ADR 012 for the reasoning.
• Update both lists when the My VA links change. The header and the side navigation don’t share a data source, so teams keep them in sync by hand. The header’s My VA links are defined in the component library, in va-header-navigation-data.ts. The side navigation links are defined in vets-website, in src/platform/my-va/navigation.js.
• People with limited access see only the links they can use. Some people who are signed in can’t open most My VA and Profile pages. This includes people who:
  • Haven’t verified their identity (LOA1 accounts)
  • Don’t have a record in the VA Master Person Index

  These people see only My VA home, My HealtheVet, Forms, Submission history, Sign-in information, and Signed-in devices. The consuming application hides the other links with the menu-item-filter prop.

• The header never offers Sign in to someone who’s signed in. While a returning person’s profile loads, the header shows the Menu button. The welcome heading shows a cached name or “Welcome” alone until the profile arrives.
• People who aren’t signed in see the main navigation in the header at vads-breakpoint-tablet-lg and wider, with no Menu button. Below vads-breakpoint-tablet-lg, they see a Menu button with a Sign in button next to it.

Responsive behavior

• The main navigation lives in the Menu button below vads-breakpoint-tablet-lg. The search link stays in the bar at every width.
• The menu fills the screen below vads-breakpoint-tablet-lg. The bar stays in place at the top, the page behind the menu doesn’t scroll, and the page is hidden from assistive technology until the menu closes.
• Sections expand in place, and subsections open their own view. In the menu below vads-breakpoint-tablet-lg, a section expands to show its subsections. A subsection with links replaces the list with its own view, headed by a “Back to [section] menu” button.
• The logo condenses to the VA wordmark below vads-breakpoint-desktop-lg.
• The layout follows the browser’s text size. Breakpoints scale with the person’s text size setting, so the header changes layout sooner when text is larger.

Choosing between variations

• Use Header - Minimal when leaving the page would keep people from finishing their task. A form flow is the most common example. The minimal header keeps VA.gov branding but removes the main navigation and Sign in.
• Hide Sign in when the page’s own flow signs the person in. For example, the check-in experience has its own sign-in step. A Sign in button in the header confused people and took them to sign in to VA.gov when they meant to check in to their appointment. Use the hide-sign-in prop in these cases.

Placement

• At the top of every page. The header appears below the Banner - Official Gov and the Veterans Crisis Line on every page in the VA.gov domain, but not on all subdomains.

Injected header

• Pages that inject the header still show the previous header. The VA.gov header is injected into other content management systems, such as Microsoft TeamSites. Web components don’t currently load in TeamSites, so those pages continue to use the previous React header. The injected header will match the visual design of the web component in future.

Code usage

Content considerations

• Navigation labels come from VA.gov’s content management system. The component ships with the current VA.gov navigation. Don’t override it with the menu-data prop except for urgent link fixes ahead of a component release, tests, or previews.
• Keep labels short. The header doesn’t truncate navigation, My VA, or Profile labels, so long labels wrap.
• Supply translated labels. The header renders My VA and Profile labels exactly as the consuming application provides them.
• Don’t add Sign out to the Profile links. The header always adds Sign out as the last item in the menu.
• Provide the person’s first and last name. The welcome heading joins them. If neither is available, provide another name, such as an email address. With no name, the heading reads “Welcome” alone.

Accessibility considerations

• The header is a navigation landmark labeled “Primary.”
• Menus use the disclosure pattern, not role="menu". The Menu button and each navigation panel trigger are buttons with aria-expanded. The WAI-ARIA Authoring Practices reserve role="menu" for application menus, not navigation links.
• Pass the current page’s path. Set current-href to the page’s path, and update it on client-side route changes, so the matching link gets aria-current="page".
• Manage focus after client-side navigation. The header doesn’t move focus when someone selects a link. Single-page applications that route on the client need to place focus after the route changes.
• Focus stays visible. Panels and menus close when keyboard focus leaves them, so they never cover the focused element. Pressing Escape closes the panel or menu and returns focus to its trigger.
• The mobile menu keeps assistive technology inside it. While the menu fills the screen, the page behind it is hidden from screen readers, and pressing Tab from the last menu item returns focus to the Menu button.
• Every target is at least 44 by 44 pixels. This meets the Web Content Accessibility Guidelines (WCAG) 2.2 enhanced target size.
• The search link keeps its accessible name at every width. The link is named “Search” even when the visible label is hidden at narrow widths.
• Color is never the only indicator. The selected benefit hub also uses a heavier font weight, and open and selected states show outlines in forced colors modes, such as Windows high contrast mode.
• You own the contrast of a translucent background. If your page makes the bar translucent, make sure the bar’s white text still meets contrast requirements over the content beneath it.

Related

• Header - Minimal
• Banner - Official Gov
• Crisis Line Modal
• Side Navigation
• Footer

Component checklist

Provide feedback

Share your feedback, report issues, or suggest improvements for the Header component. Your input helps us make the design system better for everyone.

• Get immediate support in #platform-design-system for technical or urgent issues.
• Explore all feedback channels for additional ways to share your input.