Accordion

The <nys-accordion> and <nys-accordionitem> components are vertically stacked list of headers that can be clicked to reveal or hide associated content, helping to organize and condense information.

You can apply for or renew a U.S. passport through the U.S. Department of State. Some renewals can be done by mail.

You can check your registration status, update your information, or find out how to register through the National Association of Secretaries of State.

Copy Code
<nys-accordion>
<nys-accordionitem
id="accordionId1"
heading="How do I renew my passport or apply for a new one?"
expanded
>
    <p>
      You can apply for or renew a U.S. passport through the U.S. Department
      of State. Some renewals can be done by mail.
    </p>
    <div style="display: flex; gap: 0.5rem; font-size: 1rem;">
      <a href="https://www.ny.gov" target="_blank">Check your registration</a>
      <a href="https://www.ny.gov" target="_blank">Fill out application</a>
    </div>
  </nys-accordionitem>
  <nys-accordionitem
    id="accordionId2"
    heading="How can I find out if I’m registered to vote?"
  >
    <p>
      You can check your registration status, update your information, or
      find out how to register through the National Association of
      Secretaries of State.
    </p>
  </nys-accordionitem>
</nys-accordion>

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


Accessibility

Accordion test status
Total tests Passes Fails To do
10 10 0 0

For comprehensive insight and guidance, please see Accessibility Checklists and Build Accessibly.


Options

Individual accordion

The nys-accordionitem toggles open or closed with the expanded prop. Add this prop to a nys-accordionitem to have it open by default when the component first renders.

Note: Always wrap nys-accordionitem components in a nys-accordion.

Empire ipsum dolor sit amet, across the Brooklyn Bridge to Central Park, consectetur adipiscing elit.

Copy Code
<nys-accordion>
<nys-accordionitem
id="individualAcc1"
heading="Liberty Ipsum: Bridges & Boroughs"
expanded
>
    <p>
      Empire ipsum dolor sit amet, across the Brooklyn Bridge to Central
      Park, consectetur adipiscing elit.
    </p>
  </nys-accordionitem>
</nys-accordion>

Accordion wrapper

The nys-accordion is a wrapper that holds a group of nys-accordionitem components. When the singleSelect boolean property is set, only one nys-accordionitem in the wrapper can be open at a time.

Learn about state programs, services, and resources available at ny.gov

Empire ipsum dolor sit amet, across the Brooklyn Bridge to Central Park, consectetur adipiscing elit.

From the banks of the Hudson to the peaks of the Adirondacks, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Copy Code
<nys-accordion singleSelect>
<nys-accordionitem id="accordion1" heading="Welcome to New York" expanded>
<p>
Learn about state programs, services, and resources available at
<a href="https://www.ny.gov" target="_blank">ny.gov</a>
</p>
</nys-accordionitem>
<nys-accordionitem id="accordion2" heading="Liberty Ipsum: Bridges & Boroughs">
<p>
Empire ipsum dolor sit amet, across the Brooklyn Bridge to Central
Park, consectetur adipiscing elit.
</p>
</nys-accordionitem>
<nys-accordionitem id="accordion3" heading="Hudson Ipsum: Riverfront Stories">
<p>
From the banks of the Hudson to the peaks of the Adirondacks, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua.
</p>
</nys-accordionitem>
</nys-accordion>

Bordered The bordered prop is available on nys-accordion. When set,

all nys-accordionitem inside the wrapper will display borders.

Stronger together! Learn more at ny.gov

Empire ipsum dolor sit amet, across the Brooklyn Bridge to Central Park, consectetur adipiscing elit.

From the banks of the Hudson to the peaks of the Adirondacks, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Copy Code
<nys-accordion singleSelect bordered>
<nys-accordionitem heading="We are a group of accordions">
<p>
Stronger together! Learn more at
<a href="https://www.ny.gov" target="_blank">ny.gov</a>
</p>
</nys-accordionitem>
<nys-accordionitem heading="Liberty Ipsum: Bridges & Boroughs">
<p>
Empire ipsum dolor sit amet, across the Brooklyn Bridge to Central
Park, consectetur adipiscing elit.
</p>
</nys-accordionitem>
<nys-accordionitem heading="Hudson Ipsum: Riverfront Stories">
<p>
From the banks of the Hudson to the peaks of the Adirondacks, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua.
</p>
</nys-accordionitem>
</nys-accordion>

Usage

Do

  • Use accordions for FAQs on state services like DMV procedures or benefits information.

  • Break up long program descriptions or supplemental details (such as optional steps, extra instructions, or secondary eligibility notes) into manageable sections without overwhelming the reader.

  • Label headings clearly so users understand the content before expanding.

  • Consider accordions in mobile layouts to keep pages compact while still allowing access to full details.

Don't

  • Hide time-sensitive deadlines, required steps, or critical eligibility criteria in a collapsed section. Keep essential information visible by default.

  • Use vague or unclear headings that make it hard to know what is inside.

  • Overuse accordions for content that is short enough to display fully on the page.

  • Use an accordion when users need to compare details from multiple sections at once. Consider a table or side-by-side layout instead.


    • Properties

    Property Type Default Component
    id String "" both
    heading String "" nys-accordionitem
    expanded boolean false nys-accordionitem
    bordered boolean false nys-accordion
    singleSelect boolean false nys-accordion

    Style Overrides

    These CSS custom properties are exposed for developers to customize the visual appearance of the component when necessary, beyond the defaults provided by the NYS Design System. Set them on the component selector to override the default styles.

    Copy Code
    nys-component {
  --nys-component-background-color: var(--nys-color-accent);
  --nys-component-color: var(--nys-color-ink);
}

    CSS Variable Description
    --nys-accordion-color--header The text color of the accordion header
    --nys-accordion-background-color--header Background color of the accordion header
    --nys-accordion-background-color--header--hover Background hover color of the accordion header
    --nys-accordion-content-max-width Maximum readable width of accordion content. Defaults to a character-based width (80ch) for readability.
    Can't find a property you need? Explore existing options, or propose a new one with a Component Proposal.


    Events

    Some components emit nys- events with a detail object containing the relevant data, instead of relying on native events alone. Stick to one approach per interaction, don't mix native and nys- listeners for the same thing.

    The <nys-accordionitem> component emits one custom Javascript event:

    Event details

    Name Description Return details
    nys-accordionitem-toggle Emitted when an accordion item is expanded or collapsed.
    • id (string): The id of the accordion.
    • heading (string): The accordion's heading text.
    • expanded (boolean): true if expanded, otherwise false.

    You can listen to these events using JavaScript:
    Copy Code
    // Select the accordion component
const accordion = document.querySelector("nys-accordionitem");
// Listen for the 'nys-accordionitem-toggle' event
accordion.addEventListener("nys-accordionitem-toggle", (event) => {
  console.log("Accordion toggled:", {
    id: event.detail.id,
    heading: event.detail.heading,
    expanded: event.detail.expanded
  });
});

    Dependencies

    This component automatically imports the following dependencies:

    • <nys-icon>

    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: October 9, 2026