JavaScript

The package binds Zag state machines to HTML. Import its initializers from @uswds-tailwind/compat; no framework plugin is required. For package installation and Tailwind setup, start with the getting-started guide. React components own their own behavior; do not run these initializers on React-rendered markup.

Choose an initialization strategy

Selective initialization

Import only the initializers you need. Each scans the document synchronously when called; it does not wait for the DOM, observe future additions, or return a promise.

import { accordionInit } from '@uswds-tailwind/compat/accordion'
import { collapseInit } from '@uswds-tailwind/compat/collapse'

function initialize() {
  accordionInit()
  collapseInit()
}

if (document.readyState === 'loading') {
  document.addEventListener('DOMContentLoaded', initialize, { once: true })
} else {
  initialize()
}

Root imports such as import { accordionInit } from '@uswds-tailwind/compat' expose the same functions.

Initialize all components

Choose one initialization strategy per element. The auto entry point runs initAll() immediately when the document is ready, or on DOMContentLoaded if it is still loading:

import '@uswds-tailwind/compat/auto'

To control when the scan happens, import the function instead and call it after inserting the markup:

import { initAll } from '@uswds-tailwind/compat'

// After all component markup is in the document:
initAll()

These are alternative entry points, not imports to combine. initAll() returns void. Later scans reuse existing instances and initialize newly inserted roots. Destroy instances before removing their markup.

Authored markup and generated state

Copy the complete component example, including required parts, labels, and Tailwind classes. Each reference separates authored configuration from generated state.

Boolean attributes

• v2 data booleans such as Accordion data-multiple, Combobox data-disabled, and Modal data-force-action treat the exact string "false" as false.
• Native disabled and multiple attributes follow HTML presence rules.
• Constructor precedence varies by component; check its configuration table.

Instance lifecycle

Accordion, Character Count, Collapse, Combobox, Date Picker, Date Range Picker, Dropdown, File Input, Input Mask, Modal, Table, and Tooltip support these shared methods:

All twelve convenience initializers return instance arrays and reuse existing instances. Date Picker and Date Range Picker use the same element-based lookup and cleanup methods.

For dynamic content, retain an explicit instance and destroy it before removing the owned DOM:

import { Collapse } from '@uswds-tailwind/compat/collapse'

// <section id="details" data-scope="collapse" data-part="root">
//   <button type="button" data-part="trigger">Details</button>
//   <div data-part="content">More information</div>
// </section>
const root = document.querySelector('#details')
const details = Collapse.getOrCreateInstance(root, {
  id: 'details',
  onOpenChange({ open }) {
    console.log('Requested open state:', open)
  },
})

await details.open()

// When the application removes this section:
details.destroy()
root.remove()

Cleanup

• Retain the root element reference: initialization can replace its ID.
• Destroy the instance before removing its DOM. Modal moves its root to the document body, so remove that root too.
• Start a fresh mount with fresh authored markup; destroy() does not restore the original HTML.

Changes and callbacks

Pass callbacks through explicit constructor or factory options. These are JavaScript callbacks, not automatically emitted custom DOM events. File Input exposes accepted files and validation state through instance.api; it does not provide change callbacks.

Accordion, Character Count, and Input Mask support controlled value; Collapse and Tooltip support controlled open. Table supports controlled sortDescriptor. Dropdown and Modal manage open state internally and do not accept open or onOpenChange. When you supply a supported controlled prop, your application controls that state. Change callbacks request a new value; your application must supply the updated state. Use the component’s documented initial-state options for uncontrolled state.

Wrapper open()/close() methods on Accordion, Collapse, Dropdown, and Modal return promises that settle the queued update; they do not wait for CSS transitions or update state controlled by your application. Direct connect API requests such as Input Mask’s instance.api.setValue() return no promise.

JavaScript components

All subpaths below are relative to @uswds-tailwind/compat/. Each initializer binds the corresponding authored markup; presentation-only components need no initializer.

Banner uses Collapse; Header and Language Selector use Dropdown. Time Picker uses Combobox. Ordinary styled tables need no JavaScript. Header and expandable Footer examples also use Accordion.