Skip to main content

Header

A header helps users identify where they are and provides a quick, organized way to reach the main sections of a website.


Basic Header

Component Preview

Basic Header Structure:

  • Logo/site title on the left
  • Primary navigation links on the right
  • Optional search component
  • Mobile menu button for responsive design

Note: Full header preview would conflict with page header. See the code below for implementation.


Component Code

<header class="usa-header usa-header--basic">
  <div class="usa-nav-container">
    <div class="usa-navbar">
      <div class="usa-logo">
        <em class="usa-logo__text">
          <a href="/civic-guide/" title="Home">Project Title</a>
        </em>
      </div>
      <button type="button" class="usa-menu-btn">Menu</button>
    </div>
    <nav aria-label="Primary navigation" class="usa-nav">
      <button type="button" class="usa-nav__close">
        <img src="/assets/img/usa-icons/close.svg" role="img" alt="Close" />
      </button>
      <ul class="usa-nav__primary usa-accordion">
        <li class="usa-nav__primary-item usa-nav__link">
          <a href="#" class="usa-nav-link">
            <span>Link One</span>
          </a>
        </li>
        <li class="usa-nav__primary-item usa-nav__link">
          <a href="#" class="usa-nav-link">
            <span>Link Two</span>
          </a>
        </li>
        <li class="usa-nav__primary-item usa-nav__link">
          <a href="#" class="usa-nav-link">
            <span>Link Three</span>
          </a>
        </li>
      </ul>
      <section aria-label="Search component">
        <form class="usa-search usa-search--small" role="search">
          <label class="usa-sr-only" for="search-field">Search</label>
          <input class="usa-input" id="search-field" type="search" name="search" />
          <button class="usa-button" type="submit">
            <img src="/assets/img/usa-icons-bg/search--white.svg" class="usa-search__submit-icon" alt="Search" />
          </button>
        </form>
      </section>
    </nav>
  </div>
</header>

Extended Header

Component Preview

Extended Header Structure:

  • Logo/site title in a dedicated row
  • Secondary navigation row below the logo
  • Primary navigation in expanded row
  • More space for additional navigation items
  • Optional search component

Note: Full header preview would conflict with page header. See the code below for implementation.


Component Code

<header class="usa-header usa-header--extended">
  <div class="usa-navbar">
    <div class="usa-logo">
      <em class="usa-logo__text">
        <a href="/civic-guide/" title="Home">Project Title</a>
      </em>
    </div>
    <button type="button" class="usa-menu-btn">Menu</button>
  </div>
  <nav aria-label="Primary navigation" class="usa-nav">
    <div class="usa-nav__inner">
      <button type="button" class="usa-nav__close">
        <img src="/assets/img/usa-icons/close.svg" role="img" alt="Close" />
      </button>
      <ul class="usa-nav__primary usa-accordion">
        <li class="usa-nav__primary-item usa-nav__link">
          <button type="button" class="usa-accordion__button usa-nav__link" aria-expanded="false" aria-controls="extended-nav-section-one">
            <span>Section One</span>
          </button>
          <ul id="extended-nav-section-one" class="usa-nav__submenu">
            <li class="usa-nav__submenu-item">
              <a href="#">Submenu Link One</a>
            </li>
            <li class="usa-nav__submenu-item">
              <a href="#">Submenu Link Two</a>
            </li>
          </ul>
        </li>
        <li class="usa-nav__primary-item usa-nav__link">
          <a href="#" class="usa-nav-link">
            <span>Simple Link</span>
          </a>
        </li>
      </ul>
      <div class="usa-nav__secondary">
        <ul class="usa-nav__secondary-links">
          <li class="usa-nav__secondary-item">
            <a href="#">Secondary link</a>
          </li>
          <li class="usa-nav__secondary-item">
            <a href="#">Another link</a>
          </li>
        </ul>
        <section aria-label="Search component">
          <form class="usa-search usa-search--small" role="search">
            <label class="usa-sr-only" for="extended-search-field">Search</label>
            <input class="usa-input" id="extended-search-field" type="search" name="search" />
            <button class="usa-button" type="submit">
              <img src="/assets/img/usa-icons-bg/search--white.svg" class="usa-search__submit-icon" alt="Search" />
            </button>
          </form>
        </section>
      </div>
    </div>
  </nav>
</header>

Header with Megamenu

Component Preview

Header with Megamenu Structure:

  • Full-width dropdown panels
  • Multi-column navigation layout
  • Organized link groups within each megamenu
  • Supports complex site architectures
  • Works with both basic and extended header variants

Note: Full header preview would conflict with page header. See the code below for implementation.


Component Code

<header class="usa-header usa-header--extended">
  <div class="usa-navbar">
    <div class="usa-logo">
      <em class="usa-logo__text">
        <a href="/civic-guide/" title="Home">Project Title</a>
      </em>
    </div>
    <button type="button" class="usa-menu-btn">Menu</button>
  </div>
  <nav aria-label="Primary navigation" class="usa-nav">
    <div class="usa-nav__inner">
      <button type="button" class="usa-nav__close">
        <img src="/assets/img/usa-icons/close.svg" role="img" alt="Close" />
      </button>
      <ul class="usa-nav__primary usa-accordion">
        <li class="usa-nav__primary-item usa-nav__link">
          <button type="button" class="usa-accordion__button usa-nav__link usa-current" aria-expanded="false" aria-controls="megamenu-1">
            <span>Section One</span>
          </button>
          <div id="megamenu-1" class="usa-nav__submenu usa-megamenu">
            <div class="grid-row grid-gap-4">
              <div class="usa-col">
                <ul class="usa-nav__submenu-list">
                  <li class="usa-nav__submenu-item">
                    <a href="#">Megamenu Link 1</a>
                  </li>
                  <li class="usa-nav__submenu-item">
                    <a href="#">Megamenu Link 2</a>
                  </li>
                  <li class="usa-nav__submenu-item">
                    <a href="#">Megamenu Link 3</a>
                  </li>
                </ul>
              </div>
              <div class="usa-col">
                <ul class="usa-nav__submenu-list">
                  <li class="usa-nav__submenu-item">
                    <a href="#">Megamenu Link 4</a>
                  </li>
                  <li class="usa-nav__submenu-item">
                    <a href="#">Megamenu Link 5</a>
                  </li>
                  <li class="usa-nav__submenu-item">
                    <a href="#">Megamenu Link 6</a>
                  </li>
                </ul>
              </div>
              <div class="usa-col">
                <ul class="usa-nav__submenu-list">
                  <li class="usa-nav__submenu-item">
                    <a href="#">Megamenu Link 7</a>
                  </li>
                  <li class="usa-nav__submenu-item">
                    <a href="#">Megamenu Link 8</a>
                  </li>
                  <li class="usa-nav__submenu-item">
                    <a href="#">Megamenu Link 9</a>
                  </li>
                </ul>
              </div>
            </div>
          </div>
        </li>
        <li class="usa-nav__primary-item usa-nav__link">
          <a href="#" class="usa-nav-link">
            <span>Simple Link</span>
          </a>
        </li>
      </ul>
      <div class="usa-nav__secondary">
        <section aria-label="Search component">
          <form class="usa-search usa-search--small" role="search">
            <label class="usa-sr-only" for="mega-search-field">Search</label>
            <input class="usa-input" id="mega-search-field" type="search" name="search" />
            <button class="usa-button" type="submit">
              <img src="/assets/img/usa-icons-bg/search--white.svg" class="usa-search__submit-icon" alt="Search" />
            </button>
          </form>
        </section>
      </div>
    </div>
  </nav>
</header>


Guidance

When to use the header component

Use the header component to provide primary navigation for your website or application.
Use when you need to display site branding, logo, and title consistently across all pages.
Use to give users a familiar, consistent way to navigate between major sections of your site.

When to consider something else

If your site has very few pages.
A simple landing page or single-page application may not need a full header with navigation. Consider simpler alternatives.
If you need the extended header.
Only use the extended header if you have secondary navigation needs or many primary navigation items. For most sites, the basic header is sufficient.
If you have a complex information architecture.
Consider using megamenus if you have many pages organized into distinct categories that users need to access quickly.

Usability guidance

Keep navigation items minimal.
Limit primary navigation to 4-8 items. Too many options can overwhelm users and make navigation difficult.
Use clear, concise labels.
Navigation labels should be short, descriptive, and use familiar terms. Avoid jargon or internal terminology.
Design mobile-first.
Ensure your header works well on mobile devices. The USWDS header is responsive by default, but test thoroughly on various screen sizes.
Include a search feature.
For content-rich sites, include a search component in the header to help users find information quickly.
Indicate the current page.
Use the usa-current class to highlight the current section in the navigation.

Accessibility guidance

Include a skip navigation link.
Add a "Skip to main content" link as the first focusable element on the page. This allows keyboard users to bypass repetitive navigation.
Use proper ARIA labels.
Add aria-label="Primary navigation" to the main <nav> element to identify it for screen reader users.
Ensure keyboard navigation works.
All navigation items should be focusable and operable with keyboard only. Dropdown menus should be accessible via arrow keys.
Use proper heading hierarchy.
The site title/logo should not use heading tags to avoid disrupting the page's heading hierarchy.
Provide text alternatives for icons.
Icons like the search icon and close button should have appropriate alt text or aria-label attributes.
Use aria-expanded for dropdown menus.
Toggle the aria-expanded attribute to indicate when dropdown menus are open or closed.

USWDS Documentation

For more guidance, view the USWDS Header Component Documentation.



Settings

Variable Description
$theme-header-font-family

Font family used in the header.
$theme-header-logo-text-width

Width of the logo text area.
$theme-header-max-width

Maximum width of the header content.
$theme-header-min-width

Minimum width before the mobile menu is activated.
$theme-megamenu-columns

Number of columns in the megamenu (1, 2, or 3).


Variants

Variant Description

.usa-header--basic

Simple header with logo and primary navigation in a single row.

.usa-header--extended

Header with logo row and separate navigation row for more complex navigation needs.

.usa-megamenu

Full-width dropdown panel with multi-column navigation. Apply to submenu container.

.usa-nav__submenu

Standard dropdown submenu for navigation items.

.usa-current

Indicates the current active navigation item or section.
Looking for U.S. government information and services?
Visit USA.gov