@uswds-wc/structure

USWDS Structure Components - Accordion and content organization as Web Components.

Overview

The @uswds-wc/structure package provides web component versions of USWDS components for structuring and organizing content with expandable/collapsible sections.

Installation

npm install @uswds-wc/structure lit

Components

Accordion (<usa-accordion>)

Expandable/collapsible content sections for organizing related information.

<usa-accordion>
  <h4 slot="heading">First Amendment</h4>
  <div slot="content">
    <p>Congress shall make no law respecting an establishment of religion...</p>
  </div>
</usa-accordion>

<usa-accordion>
  <h4 slot="heading">Second Amendment</h4>
  <div slot="content">
    <p>A well regulated Militia, being necessary to the security of a free State...</p>
  </div>
</usa-accordion>

<usa-accordion>
  <h4 slot="heading">Third Amendment</h4>
  <div slot="content">
    <p>No Soldier shall, in time of peace be quartered in any house...</p>
  </div>
</usa-accordion>

Properties:

• expanded - Control accordion expansion state
• bordered - Add border around accordion
• multiselectable - Allow multiple accordions to be open simultaneously (when grouped)

Events:

• accordion-toggle - Fired when accordion is opened/closed with { detail: { expanded: boolean } }

Usage Example

Basic Accordion

import '@uswds-wc/structure';

const accordion = document.createElement('usa-accordion');
accordion.innerHTML = `
  <h4 slot="heading">Click to expand</h4>
  <div slot="content">
    <p>Hidden content that appears when expanded.</p>
  </div>
`;

document.body.appendChild(accordion);

Accordion Group (Single Open)

By default, when you have multiple accordions in a container, USWDS behavior allows only one to be open at a time.

<div class="usa-accordion-group">
  <usa-accordion>
    <h4 slot="heading">Section 1</h4>
    <div slot="content">
      <p>Content for section 1.</p>
    </div>
  </usa-accordion>

  <usa-accordion>
    <h4 slot="heading">Section 2</h4>
    <div slot="content">
      <p>Content for section 2.</p>
    </div>
  </usa-accordion>

  <usa-accordion>
    <h4 slot="heading">Section 3</h4>
    <div slot="content">
      <p>Content for section 3.</p>
    </div>
  </usa-accordion>
</div>

Multiselectable Accordion Group

Allow multiple sections to be open simultaneously:

<div class="usa-accordion-group" data-allow-multiple>
  <usa-accordion multiselectable>
    <h4 slot="heading">Section 1</h4>
    <div slot="content">
      <p>Content for section 1.</p>
    </div>
  </usa-accordion>

  <usa-accordion multiselectable>
    <h4 slot="heading">Section 2</h4>
    <div slot="content">
      <p>Content for section 2.</p>
    </div>
  </usa-accordion>
</div>

Bordered Accordion

<usa-accordion bordered>
  <h4 slot="heading">Important Information</h4>
  <div slot="content">
    <p>Content with border styling for emphasis.</p>
  </div>
</usa-accordion>

Programmatic Control

const accordion = document.querySelector('usa-accordion');

// Open accordion
accordion.expanded = true;

// Close accordion
accordion.expanded = false;

// Toggle accordion
accordion.expanded = !accordion.expanded;

// Listen for changes
accordion.addEventListener('accordion-toggle', (e) => {
  console.log('Accordion is now:', e.detail.expanded ? 'open' : 'closed');
});

FAQ Example

<h2>Frequently Asked Questions</h2>

<div class="usa-accordion-group">
  <usa-accordion>
    <h4 slot="heading">How do I apply?</h4>
    <div slot="content">
      <p>You can apply online through our application portal. The process takes approximately 15 minutes to complete.</p>
      <usa-button href="/apply">Start Application</usa-button>
    </div>
  </usa-accordion>

  <usa-accordion>
    <h4 slot="heading">What documents do I need?</h4>
    <div slot="content">
      <ul>
        <li>Government-issued photo ID</li>
        <li>Proof of residency</li>
        <li>Income verification</li>
        <li>Social Security card</li>
      </ul>
    </div>
  </usa-accordion>

  <usa-accordion>
    <h4 slot="heading">How long does processing take?</h4>
    <div slot="content">
      <p>Applications are typically processed within 5-7 business days. You will receive an email notification when your application status changes.</p>
    </div>
  </usa-accordion>

  <usa-accordion>
    <h4 slot="heading">Can I check my application status?</h4>
    <div slot="content">
      <p>Yes, you can check your application status at any time by logging into your account.</p>
      <usa-button variant="outline" href="/login">Check Status</usa-button>
    </div>
  </usa-accordion>
</div>

Bundle Size

Gzipped: ~20 KB

Features

• USWDS Behavior - Exact implementation of USWDS accordion JavaScript
• Keyboard Navigation - Full keyboard support (Enter, Space, Arrow keys)
• Accessibility - Proper ARIA attributes and roles
• Smooth Animations - CSS transitions for expand/collapse
• Flexible Content - Support any HTML content in slots
• Group Behavior - Single-open or multi-open modes
• TypeScript - Full type definitions included

Accessibility Features

• ARIA Attributes - Proper aria-expanded, aria-controls, aria-labelledby
• Keyboard Support:
  • Enter or Space - Toggle accordion
  • Tab - Move between accordions
• Focus Management - Visible focus indicators
• Screen Readers - Announces expansion state changes

Browser Support

• Modern browsers (Chrome, Firefox, Safari, Edge)
• ES2020+ required
• Web Components v1 spec

Dependencies

• @uswds-wc/core - Core utilities and base components
• lit ^3.0.0 (peer dependency)

Development

# Build the package
pnpm run build

# Run tests
pnpm test

# Type checking
pnpm run typecheck

# Linting
pnpm run lint

Storybook

View live examples and interactive documentation:

USWDS Web Components Storybook

License

MIT

Repository

USWDS Web Components Monorepo

Related Packages

• @uswds-wc/all - Complete package bundle
• @uswds-wc/layout - Layout and organization components
• @uswds-wc/data-display - Data display components

Contributing

See the main repository for contribution guidelines.