Autocomplete

v1.1.5

Ready for Production

Catalyst Autocomplete goes with built-in design tokens, CVA variants, and accessibility defaults — so you get production-ready autocomplete with zero config. It displays suggestions in a dropdown as users type, with loading states, error handling, and keyboard navigation support.

Installation

npm install @pmi/catalyst-autocomplete

import {
  AutocompleteRoot,
  AutocompleteInputRoot,
  AutocompleteInput,
  AutocompleteInputSlot,
  AutocompleteLabel,
  AutocompletePortal,
  AutocompleteContent,
  AutocompleteViewport,
  AutocompleteItem,
  AutocompleteItemText,
  AutocompleteScrollUpButton,
  AutocompleteScrollDownButton,
} from '@pmi/catalyst-autocomplete';

Sizes

Common Patterns

Danger State

Use the danger prop to indicate an error state, such as when validation fails.

Disabled State

API Reference

AutocompleteRoot

Extends all standard HTML div element props. The root container that manages the autocomplete state and behavior.

AutocompleteInputRoot

Extends all standard HTML div element props. Container for the input field and its decorative slots. Forwards ref to the underlying HTMLDivElement.

AutocompleteInput

Extends all standard HTML input element props. The text input element where users type their search query. Forwards ref to the underlying HTMLInputElement.

AutocompleteInputSlot

Extends all standard HTML div element props. Decorative slots for icons or buttons on the left or right side of the input. Forwards ref to the underlying HTMLDivElement.

AutocompleteContent

Extends all standard HTML div element props. The dropdown container for suggestions. Forwards ref to the underlying HTMLDivElement.

AutocompleteItem

Extends all standard HTML div element props. An individual suggestion item in the dropdown. Forwards ref to the underlying HTMLDivElement.

AutocompleteLabel

Extends all standard HTML div element props. Optional label for grouping suggestions. Forwards ref to the underlying HTMLDivElement.

AutocompleteScrollUpButton

Extends all standard HTML div element props. Button displayed at the top of the dropdown when the list can be scrolled upward. Forwards ref to the underlying HTMLDivElement.

AutocompleteScrollDownButton

Extends all standard HTML div element props. Button displayed at the bottom of the dropdown when the list can be scrolled downward. Forwards ref to the underlying HTMLDivElement.

Data Attributes

• [data-state]: "open" | "closed" - Applied to AutocompleteContent
• [data-disabled]: Present when disabled - Applied to AutocompleteRoot
• [data-size]: "sm" | "md" | "lg" - Applied to AutocompleteRoot
• [data-danger]: Present when danger=true - Applied to AutocompleteRoot

Accessibility

Keyboard Interactions

ARIA

• Provide an aria-label on AutocompleteInputRoot
• Screen Readers: Proper ARIA roles and labels for combobox functionality are added
• Live Regions: Suggestions are announced as they appear
• State Announcement: Loading, error, and empty states are announced to assistive technology

Choosing the Right Component

Use Autocomplete when you need a search input with a list of suggestions. Reach for a different primitive when:

Related

• Select
• TextField