Forms

SearchInput

A fully accessible autocomplete/combobox component following WAI-ARIA 1.2 pattern. Supports async search, keyboard navigation, grouped options, and custom rendering. Perfect for patient, provider, and payer search workflows.

Basic Usage

Type to search and select from available options. Includes debounced search, keyboard navigation, and clear functionality.

Search Patient

With Custom Icon

Replace the default search icon with a contextual icon for better visual communication.

Insurance Payer

Location

Grouped Options

Organize options into logical groups for better discoverability. Useful for provider directories with specialties.

Find a Provider

Async Search with Loading

Handle asynchronous search with loading states. Results are fetched from an API as you type.

Patient Lookup

Custom Option Rendering

Use snippets to customize how options are displayed. Add badges, icons, or additional metadata.

Select Payer

Validation States

Display validation feedback with error and success states. Use validateOnMount to show state immediately.

Required Patient Selection

Disabled Search

Size Variants

Choose appropriate sizes based on form density and visual hierarchy.

Small

Medium (Default)

Large

Custom Empty State

Provide helpful empty states when no results are found.

Patient Search

Props

Prop	Type	Default	Description
`id`	`string`	—	Unique identifier for the input
`name`	`string`	—	Form field name
`label` *	`string`	—	Label text for the input
`value`	`string`	''	Current search query (bindable)
`selected`	`SearchOption \| null`	—	Currently selected option (bindable)
`placeholder`	`string`	'Search...'	Placeholder text
`options`	`SearchOption[] \| SearchOptionGroup[]`	[]	Options to display in dropdown
`required`	`boolean`	false	Whether the field is required
`disabled`	`boolean`	false	Whether the field is disabled
`readonly`	`boolean`	false	Whether the field is read-only
`error`	`string`	—	Error message to display
`hint`	`string`	—	Hint text to display below the input
`successMessage`	`string`	—	Success message when valid
`size`	`'sm' \| 'md' \| 'lg'`	'md'	Size of the input
`hideLabel`	`boolean`	false	Hide label visually (still accessible)
`loading`	`boolean`	false	Show loading spinner during search
`emptyMessage`	`string`	'No results found'	Message when no results
`minSearchLength`	`number`	1	Minimum characters before search
`debounceMs`	`number`	300	Debounce delay in milliseconds
`clearable`	`boolean`	true	Show clear button when has value
`openOnFocus`	`boolean`	false	Open dropdown on focus
`autoSelect`	`boolean`	false	Auto-select first option
`allowFreeText`	`boolean`	false	Allow values not from options
`iconLeft`	`Snippet`	—	Custom left icon (default: Search icon)
`optionContent`	`Snippet<[SearchOption]>`	—	Custom option rendering
`emptyContent`	`Snippet`	—	Custom empty state content
`loadingContent`	`Snippet`	—	Custom loading content
`onsearch`	`(query: string) => void`	—	Called when search query changes (debounced)
`onselect`	`(option: SearchOption) => void`	—	Called when an option is selected
`onclear`	`() => void`	—	Called when selection is cleared
`testId`	`string`	—	Test ID for e2e testing
`validateOnMount`	`boolean`	false	Show validation state immediately

Types

interface SearchOption {
  value: string;           // Unique identifier
  label: string;           // Display text
  disabled?: boolean;      // Option disabled state
  description?: string;    // Secondary text
  icon?: Component;        // Optional icon component
  metadata?: Record<string, unknown>; // Custom data
}

interface SearchOptionGroup {
  label: string;           // Group header
  options: SearchOption[]; // Options in this group
}

Keyboard Navigation

Key	Action
`↓`	Open dropdown / Move to next option
`↑`	Move to previous option
`Enter`	Select highlighted option
`Escape`	Close dropdown
`Home`	Move to first option
`End`	Move to last option
`Tab`	Close dropdown and move focus

Healthcare Best Practices

• Always include patient identifiers (MRN, DOB) in search results to prevent misidentification
• Use debounced search to reduce API calls and improve performance with large datasets
• Group providers by specialty or location for easier navigation in large directories
• Provide clear empty states with actionable next steps (e.g., "Add new patient")
• Mark disabled options clearly when providers aren't accepting new patients or are unavailable
• Implement proper validation for required selections before form submission
• Ensure all interactions work with keyboard only for accessibility compliance
• Consider using async search for large datasets to avoid loading all data upfront

Accessibility Features

• WAI-ARIA Combobox Pattern: Full implementation of ARIA 1.2 combobox with listbox popup
• Keyboard Navigation: Complete arrow key, Home, End, Enter, and Escape support
• Screen Reader Support: Announces result count, selected items, and state changes
• Focus Management: Maintains focus in input while navigating options via aria-activedescendant
• Reduced Motion: Respects user's motion preferences for animations
• Clear Labels: Proper labeling and descriptions for all interactive elements