@uswds-wc/core

Core utilities and base components for USWDS Web Components.

Overview

The @uswds-wc/core package provides the foundational building blocks for all USWDS Web Components. It includes base classes, utilities, and shared functionality that other packages depend on.

Installation

# Using pnpm (recommended)
pnpm add @uswds-wc/core lit

# Using npm
npm install @uswds-wc/core lit

# Using yarn
yarn add @uswds-wc/core lit

Note: This package is typically installed as a dependency of other @uswds-wc/* packages and doesn't need to be installed directly unless you're building custom USWDS components.

What's Included

Base Components

• USWDSBaseComponent - Base class for all USWDS web components
  • Automatic Light DOM rendering
  • USWDS initialization lifecycle
  • Consistent component behavior

Utilities

• Accessibility utilities - ARIA helpers, focus management
• DOM utilities - Element manipulation, class management
• Event utilities - Custom event helpers
• Validation utilities - Form validation helpers

USWDS Styles

The package includes compiled USWDS CSS that can be imported:

import '@uswds-wc/core/styles.css';

Usage

Extending USWDSBaseComponent

import { USWDSBaseComponent } from '@uswds-wc/core';
import { html } from 'lit';

export class MyCustomComponent extends USWDSBaseComponent {
  render() {
    return html`
      <div class="usa-component">
        <!-- Your USWDS markup -->
      </div>
    `;
  }

  override firstUpdated() {
    super.firstUpdated();
    this.initializeUSWDSComponent();
  }
}

Using Utilities

import { setAriaLabel, manageFocus } from '@uswds-wc/core/utils/accessibility';
import { toggleClass } from '@uswds-wc/core/utils/dom';

Features

• Light DOM - All components render without Shadow DOM for maximum USWDS compatibility
• USWDS Integration - Automatic initialization of USWDS JavaScript behaviors
• TypeScript Support - Full type definitions included
• Tree Shakeable - Import only what you need

Browser Support

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

Dependencies

• 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

License

MIT

Repository

USWDS Web Components Monorepo

Related Packages

• @uswds-wc/actions - Action components (Button, Link, Search)
• @uswds-wc/forms - Form components
• @uswds-wc/navigation - Navigation components
• @uswds-wc/data-display - Data display components
• @uswds-wc/feedback - Feedback components
• @uswds-wc/layout - Layout components
• @uswds-wc/structure - Structure components
• @uswds-wc/all - Complete package bundle

Contributing

See the main repository for contribution guidelines.