Skip to main content
U.S. Flag

An official website of the United States government

CMS Design System Header


This component is only used for HealthCare. Please use the theme switcher to view the component with HealthCare styles.


The header component varies depending on the user's state (ie. logged-in) and context (ie. what page the user is on).









React Properties Documentation
classNamestringAdditional classes to be added to the root <header> element.
switchLocaleLinkstringFor applications that handle their own locale switching. Overrides the default locale link. This takes precedence over the subpath prop.
loggedInbooleanIndicate that a user is logged-in.
hideLoginLinkbooleanWhen set to true, do not display the Login text in the upper right of the header
hideLogoutLinkbooleanWhen set to true, even if logged in the Logout link will not render
hideLanguageSwitchbooleanWhen set to true, do not display the the switch locale link
firstNamestringFor logged-in users, pass in their first name to display in the header
subpathstringFor applications hosted at paths other than the root This string will be appended to the end of the language links so as to keep the user within the same part of the site when switching languages.
primaryDomainstringThe primary, or root domain where the majority of header links should be hosted. By default, links render with relative paths, but providing this prop will force all links to render with absolute paths based on the provided string. The string should include the protocol (http:// or https://) and the domain only, with no trailing slash. For example, if the provided string is, the login link will render as instead of just /login. Note that this is only really necessary if your application is hosted on a subdomain, such as, where relative links would direct the user to the wrong location, e.g. the link to /login would incorrectly direct the user to when it should direct the user to
skipNavHrefstring#mainA URL hash used for the "Skip to main content" link. This is typically the id of your "main" content area (ie. #main).
onSkipNavClick(...args: any[]) => anyAn onClick handler used for the "Skip to main content" link. This can be used in cases where one would need to manually set the focus on the content area (e.g. where hash routing is being used).
deConsumerbooleanIndicates when a consumer is coming from a Direct Enrollment flow. This will include additional messaging and modify some of the links.
deBrokerNamestringUsed in conjunction with deConsumer, the Direct Enrollment broker's name is used in some of the messaging displayed to the consumer.
linksLink[]Optionally pass in an array of link objects to override the default set of menu links. This may be useful if you need to customize the links on a page-by-page basis. To reference the default set of menu links, you can import the defaultMenuLinks method.
submenuTopReactNodeOptionally pass a React component to render within the menu. Useful for when you need more control over what appears in the menu than what's provided by the links prop, e.g. a search input. Will appear above any links provided by the defaultMenuLinks method or the links provided by the links prop.
submenuBottomReactNodeSame as submenuTop, except it will appear below any links provided by the defaultMenuLinks method or the links provided by the links prop.
headerBottomReactNodeElement added to display content on Header bottom section
isMenuOpenbooleanOpen and handler function for fully controlled menu behavior
onMenuToggle() => void
logoClassNamestringAdditional classes to be added to the Logo component

Google Analytics

Analytics event tracking is enabled by default.

On applications where the page has utag loaded, the data goes to Tealium which allows it to route to Google Analytics or the currently approved data analytics tools.

Disabling event tracking

Import and set the setHeaderSendsAnalytics feature flag to false in your application's entry file:

import { setHeaderSendsAnalytics } from "@cmsgov/<design-system-package>";

Component maturity

For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.


  • Color

    Meets AA color contrast standards for accessibility and color blindness.
  • Forced Colors Mode (FCM)

    While using FCM the components text is legible and improves readability.
  • WCAG 2.1 Level AA Conformance

    All Axe checks for WCAG AA compliance have passed.
  • Screen readers

    VoiceOver, NVDA, and JAWS screen readers provide concise communication and interaction.
  • Keyboard navigation

    Component is fully navigable with a keyboard.


  • Storybook

    Component has stories to cover all defined props.
  • Responsive

    Component designed to work in all responsive breakpoints.
  • Spanish translations

    Includes Spanish translations for default text content.


  • Code

    Tokens implemented in code.
  • Design

    Tokens implemented in the Sketch.