Global Header

The <nys-globalheader> component renders an agency-branded header with application and agency names, primary navigation links, and a responsive mobile menu. It sits below <nys-unavheader> and automatically highlights the active navigation link based on the current URL.

Copy Code
<nys-globalheader 
  appName="User Registration Form" 
  agencyName="Office of Information Technology Services"
></nys-globalheader>

Can't use NYS Design System web components in your project? Try using the CSS Variables instead.


Accessibility

The <nys-globalheader> component includes the following accessibility-focused features:

  • Renders a <header> landmark element, which screen readers identify as a banner region. Users can navigate directly to this landmark using assistive technology shortcuts.

  • All navigation links use standard <a> elements and are fully keyboard-focusable.

  • On narrow screens (below 1024px), navigation collapses into a mobile menu toggled by a button with a visible "MENU" / "CLOSE" label and corresponding icon.

  • The active navigation link is visually highlighted with a bold font weight and bottom border (desktop) or left border (mobile), providing clear orientation.

  • When using <nys-skipnav> on your page, it should target your main content area. The Global Header provides the banner landmark that skip navigation helps users bypass.

  • The user-actions slot supports keyboard-accessible controls like log-out buttons, maintaining tab order within the header.

    Additional accessibility test and build content is coming soon, in a new format.


Options

For public-facing sites, the Global Header can include navigation links. To add links, follow this format:

  1. Use an unordered list (<ul>) inside the <nys-globalheader> slot.
  2. Each list item (<li>) should contain an anchor (<a href="">) linking to the desired URL.

Use the prop homepageLink to link your agencyName to your homepage.

The component automatically highlights the active link based on the current URL path. It matches the most specific path, so /services/benefits will match before /services.

Note: On screens below 1024px, navigation links collapse into a mobile menu. A "MENU" button appears to the left of the header content and toggles the full link list. Applications using the Global Header typically do not include links in the application or agency name to reduce distractions. Public-facing sites may include them to aid navigation.

Copy Code
<nys-globalheader homepageLink="https://ny.gov" agencyName="Office of Information Technology Services">
  <ul>
    <li><a href="https://its.ny.gov/services">Services</a></li>
    <li><a href="https://its.ny.gov/get-help">Help Center</a></li>
    <li><a href="https://its.ny.gov/cybersecurity">Cybersecurity</a></li>
    <li><a href="https://its.ny.gov/policies">Policies and Laws</a></li>
    <li><a href="https://its.ny.gov/procurement">Procurement</a></li>
    <li><a href="https://its.ny.gov/about-us">About Us</a></li>
  </ul>
</nys-globalheader>

Just Agency Name

Use the prop homepageLink to link your agencyName to your homepage.

Copy Code
<nys-globalheader agencyName="Office of Information Technology Services">
</nys-globalheader>

Just Application Name

Copy Code
<nys-globalheader appName="NYS Employee Portal"></nys-globalheader>

User Actions

The <nys-globalheader> component includes a named slot called user-actions. This slot allows you to insert custom HTML content, such as user profile links, settings, or logout buttons, into the header.

Copy Code
<nys-globalheader appName="User Registration Form" agencyName="Office of Information Technology Services">
  <nys-button id="my-action-slot" slot="user-actions" label="John Smith" prefixIcon="slotted">
    <nys-avatar
      slot="prefix-icon"
      ariaLabel="User avatar"
      initials="JS"
      ></nys-avatar>
  </nys-button>
</nys-globalheader>
<nys-dropdownmenu id="dropdownmenu" for="my-action-slot">
  <nys-dropdownmenuitem label="Profile" href="/profile"></nys-dropdownmenuitem>
  <nys-dropdownmenuitem label="Repositories & Github Pages" href="/repos"></nys-dropdownmenuitem>
  <nys-dropdownmenuitem label="Organizations" href="/organizations" disabled></nys-dropdownmenuitem>
  <nys-dropdownmenuitem label="Sign out" href="/logout"></nys-dropdownmenuitem>
</nys-dropdownmenu>

The NYS Brand Logo can be toggled on via the nysLogo property for back-office applications.

Note: Do not use the NYS brand mark on public-facing applications. This is intended exclusively for internal and back-office use.

Copy Code
<nys-globalheader nysLogo appName="Admin Dashboard"></nys-globalheader>

Usage

Do

  • Use on every agency site and application. The Global Header is a required page element.
  • Place below <nys-unavheader> when using the Universal Navigation Header.
  • Use agencyName alone for public-facing agency websites not tied to a specific application; omit it for statewide portals that aren't agency-specific.
  • Use appName for named applications (e.g., "Employee Time Tracker" or "License Renewal Portal").
  • Combine appName and agencyName when an application belongs to a specific agency.
  • Set homepageLink to make the header title clickable. On public-facing sites, this is the primary path back to the homepage.
  • Use the user-actions slot for authenticated applications that need log-out buttons or user profile controls.
  • Keep navigation link lists to 6 items or fewer. On mobile, these collapse into a full-width menu.
  • Add the nysLogo property to display the NYS brand mark for internal applications that don't require public-facing agency branding.

Don't

  • Don't use appName for an agency name. Use the agencyName prop instead.
  • Don't add navigation links to application headers where users should remain focused on a task (e.g., a multi-step form).
  • Don't place secondary or utility navigation in the Global Header. Use <nys-globalfooter> for secondary links.
  • Don't use the nysLogo property on public-facing sites, instead use the <nys-unavheader> for statewide branding.

Properties

Property Type Default
id String ""
agencyName String ""
appName String ""
homepageLink String (URL) ""

Style Overrides

There are no existing CSS variables for this component. Explore existing options, or propose a new one with a Component Proposal.


Events

This component does not emit any custom events.

Suggest a New Component

Do you have an idea for a new NYS Design System web component? Look through the existing proposals in our GitHub discussions board to see if someone already proposed something similar. If not, feel free to submit one.

Edit this page on GitHub (Permissions required)

Last updated: June 18, 2026