@uswds-wc/actions

USWDS Action Components - Buttons, Links, and Search functionality as Web Components.

Overview

The @uswds-wc/actions package provides web component versions of USWDS action-related components. These components enable user interactions like clicking buttons, following links, and performing searches.

Installation

npm install @uswds-wc/actions lit

Components

Button (<usa-button>)

Standard USWDS button with all variants and states.

<usa-button>Default Button</usa-button>
<usa-button variant="secondary">Secondary</usa-button>
<usa-button variant="accent-cool">Accent Cool</usa-button>
<usa-button size="big">Big Button</usa-button>
<usa-button disabled>Disabled</usa-button>

Properties:

• variant: 'default' | 'secondary' | 'accent-cool' | 'accent-warm' | 'base' | 'outline' | 'unstyled'
• size: 'default' | 'big'
• disabled: boolean
• type: 'button' | 'submit' | 'reset'

Button Group (<usa-button-group>)

Groups related buttons together with consistent spacing.

<usa-button-group>
  <usa-button>Button 1</usa-button>
  <usa-button variant="outline">Button 2</usa-button>
  <usa-button variant="outline">Button 3</usa-button>
</usa-button-group>

<usa-button-group segmented>
  <usa-button>Segmented 1</usa-button>
  <usa-button>Segmented 2</usa-button>
</usa-button-group>

Properties:

• segmented: boolean - Creates visually connected buttons

Link (<usa-link>)

USWDS styled links with external link support.

<usa-link href="/page">Internal Link</usa-link>
<usa-link href="https://example.com" external>External Link</usa-link>
<usa-link variant="unstyled" href="/unstyled">Unstyled Link</usa-link>

Properties:

• href: string - Link destination
• external: boolean - Adds external link icon and behavior
• variant: 'default' | 'unstyled'

Search (<usa-search>)

USWDS search component with form submission.

<usa-search></usa-search>
<usa-search size="small"></usa-search>
<usa-search size="big"></usa-search>
<usa-search placeholder="Search documentation..."></usa-search>

Properties:

• size: 'default' | 'small' | 'big'
• placeholder: string - Input placeholder text
• value: string - Current search value

Events:

• search-submit: Fired when search is submitted with { detail: { value: string } }

Usage Example

import '@uswds-wc/actions';

// All components are now available
const button = document.createElement('usa-button');
button.textContent = 'Click me';
button.addEventListener('click', () => console.log('Clicked!'));

With Lit

import { LitElement, html } from 'lit';
import '@uswds-wc/actions';

class MyApp extends LitElement {
  render() {
    return html`
      <usa-button @click=${this.handleClick}>
        Submit
      </usa-button>

      <usa-search
        @search-submit=${this.handleSearch}
        placeholder="Search...">
      </usa-search>
    `;
  }

  handleClick() {
    console.log('Button clicked');
  }

  handleSearch(e) {
    console.log('Search query:', e.detail.value);
  }
}

Bundle Size

Gzipped: ~30 KB

Features

• Full USWDS Compliance - Matches official USWDS HTML structure and CSS
• Accessibility - WCAG 2.1 AA compliant with proper ARIA attributes
• TypeScript - Full type definitions included
• Tree Shakeable - Import individual components to reduce bundle size
• Framework Agnostic - Works with any framework or vanilla JS

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/forms - Form components
• @uswds-wc/navigation - Navigation components

Contributing

See the main repository for contribution guidelines.