React Autocomplete

https://github.com/szhsin/react-autocomplete
Admin
React Autocomplete is a modular, lightweight, and headless autocomplete, combobox, and select...
Tokens:38,403
Snippets:416
Trust Score:9.2
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install project dependencies

Source: https://github.com/szhsin/react-autocomplete/blob/master/website/README.md

Run this command to install all necessary packages for the website.

```bash
$ npm install
```

--------------------------------

### Install the library

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/API-OVERVIEW.md

Use npm to add the package to your project.

```bash
npm install @szhsin/react-autocomplete
```

--------------------------------

### Install @szhsin/react-autocomplete

Source: https://github.com/szhsin/react-autocomplete/blob/master/website/docs/docs/install.mdx

Use these commands to add the library to your project dependencies.

```bash
npm install @szhsin/react-autocomplete
```

```bash
yarn add @szhsin/react-autocomplete
```

```bash
pnpm add @szhsin/react-autocomplete
```

```bash
bun add @szhsin/react-autocomplete
```

--------------------------------

### Start development server

Source: https://github.com/szhsin/react-autocomplete/blob/master/examples/README.md

Executes the local development environment for the Next.js project.

```bash
npm run dev
```

--------------------------------

### Implement Basic Autocomplete

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/api-reference/features.md

A complete example showing how to use autocompleteLite with useCombobox.

```typescript
import { useCombobox, autocompleteLite } from '@szhsin/react-autocomplete';

function BasicAutocomplete() {
  const [value, setValue] = useState('');
  const [selected, setSelected] = useState<string | undefined>();

  const {
    getInputProps,
    getListProps,
    getItemProps,
    getClearProps,
    isInputEmpty,
    open,
    focusIndex
  } = useCombobox({
    value,
    onChange: setValue,
    selected,
    onSelectChange: setSelected,
    items: ['Apple', 'Apricot', 'Avocado', 'Banana', 'Blueberry'],
    feature: autocompleteLite({
      select: false,
      rovingText: true
    })
  });

  return (
    <div>
      <div style={{ position: 'relative', display: 'inline-block' }}>
        <input {...getInputProps()} placeholder="Search fruits..." />
        {!isInputEmpty && (
          <button {...getClearProps()} title="Clear">
            ✕
          </button>
        )}
      </div>
      {open && (
        <ul {...getListProps()} style={{ listStyle: 'none', margin: '5px 0', padding: 0 }}>
          {['Apple', 'Apricot', 'Avocado', 'Banana', 'Blueberry'].map((item, index) => (
            <li
              key={item}
              {...getItemProps({ item, index })}
              style={{ padding: '8px', backgroundColor: focusIndex === index ? '#e0e0e0' : 'white' }}
            >
              {item}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}
```

--------------------------------

### Start local development server

Source: https://github.com/szhsin/react-autocomplete/blob/master/website/README.md

Launches a local server with live reloading for development purposes.

```bash
$ npm start
```

--------------------------------

### Select Dropdown Implementation

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/api-reference/features.md

Usage example of the dropdown feature with an auto-populated input.

```typescript
import { useCombobox, dropdown } from '@szhsin/react-autocomplete';

function SelectDropdown() {
  const [value, setValue] = useState('');
  const [selected, setSelected] = useState<string | undefined>();

  const {
    getInputProps,
    getListProps,
    getItemProps,
    getToggleProps,
    open,
    focusIndex
  } = useCombobox({
    value,
    onChange: setValue,
    selected,
    onSelectChange: setSelected,
    items: ['Red', 'Green', 'Blue'],
    feature: dropdown()
  });

  return (
    <div style={{ position: 'relative', display: 'inline-block', width: '200px' }}>
      <input {...getInputProps()} readOnly style={{ width: '100%' }} />
      <button {...getToggleProps()} style={{ position: 'absolute', right: 0 }}>
        ▼
      </button>
      {open && (
        <ul {...getListProps()} style={{ position: 'absolute', width: '100%' }}>
          {['Red', 'Green', 'Blue'].map((item, index) => (
            <li
              key={item}
              {...getItemProps({ item, index })}
              style={{
                padding: '8px',
                backgroundColor: focusIndex === index ? '#f0f0f0' : 'white',
                cursor: 'pointer'
              }}
            >
              {item}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}
```

--------------------------------

### Complete Autocomplete Implementation

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/api-reference/features.md

Usage example of the autocomplete feature with a toggle button and label.

```typescript
import { useCombobox, autocomplete } from '@szhsin/react-autocomplete';

function CompleteAutocomplete() {
  const {
    getLabelProps,
    getInputProps,
    getListProps,
    getItemProps,
    getToggleProps,
    open
  } = useCombobox({
    value,
    onChange: setValue,
    feature: autocomplete(),
    items: fruits
  });

  return (
    <div>
      <label {...getLabelProps()}>Fruit:</label>
      <div style={{ position: 'relative', display: 'inline-block' }}>
        <input {...getInputProps()} />
        <button {...getToggleProps()}>▼</button>
        {open && (
          <ul {...getListProps()}>
            {fruits.map((item, index) => (
              <li key={item} {...getItemProps({ item, index })}>
                {item}
              </li>
            ))}
          </ul>
        )}
      </div>
    </div>
  );
}
```

--------------------------------

### Basic Multi-Select Implementation

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/api-reference/hooks.md

A complete example demonstrating how to use useMultiSelect to manage a list of tags with selection and removal capabilities.

```typescript
import { useMultiSelect, multiSelect } from '@szhsin/react-autocomplete';

type Tag = { label: string; id: string };
const availableTags: Tag[] = [
  { label: 'React', id: 'react' },
  { label: 'Vue', id: 'vue' },
  { label: 'Angular', id: 'angular' }
];

function TagSelector() {
  const [value, setValue] = useState('');
  const [selected, setSelected] = useState<Tag[]>([]);

  const {
    getInputProps,
    getListProps,
    getItemProps,
    removeSelect,
    open,
    isItemSelected
  } = useMultiSelect({
    value,
    onChange: setValue,
    selected,
    onSelectChange: setSelected,
    getItemValue: (item) => item.label,
    feature: multiSelect(),
    items: availableTags.filter(t =>
      t.label.toLowerCase().includes(value.toLowerCase())
    )
  });

  return (
    <div>
      <div style={{ marginBottom: '10px' }}>
        {selected.map(tag => (
          <span key={tag.id} style={{ marginRight: '5px' }}>
            {tag.label}
            <button
              onClick={() => removeSelect(tag)}
              aria-label={`Remove ${tag.label}`}
            >
              ✕
            </button>
          </span>
        ))}
      </div>
      <input {...getInputProps()} placeholder="Add tags..." />
      {open && (
        <ul {...getListProps()}>
          {availableTags.map((item, index) => (
            <li
              key={item.id}
              {...getItemProps({ item, index })}
              style={{ fontWeight: isItemSelected(item) ? 'bold' : 'normal' }}
            >
              {item.label}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}
```

--------------------------------

### Configure basic autocomplete

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/configuration.md

Standard setup for a basic autocomplete combobox using a custom item value converter.

```typescript
const config = {
  value: searchInput,
  onChange: setSearchInput,
  items: filteredFruits,
  selected: selectedFruit,
  onSelectChange: setSelectedFruit,
  getItemValue: (fruit) => fruit.name,
  feature: autocomplete()
};

useCombobox(config);
```

--------------------------------

### Compose Features with autoFocus

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/api-reference/features.md

Example of merging autocompleteLite and autoFocus using mergeModules.

```typescript
import { useCombobox, autocompleteLite, autoFocus, mergeModules } from '@szhsin/react-autocomplete';

const autocompleteFocus = (props) =>
  mergeModules(
    autocompleteLite(props),
    autoFocus(props)
  );

// Then use with feature prop
feature: autocompleteFocus({ onRequestItem: (e, res) => { ... } })
```

--------------------------------

### useCombobox Error Handling and Filtering

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/api-reference/hooks.md

An example demonstrating item filtering and conditional disabling of items.

```typescript
function SafeFruitPicker() {
  const [value, setValue] = useState('');
  const [selected, setSelected] = useState<Fruit | undefined>();
  const [items, setItems] = useState<Fruit[]>([]);

  const {
    getInputProps,
    getListProps,
    getItemProps,
    open,
    focusIndex
  } = useCombobox({
    value,
    onChange: setValue,
    selected,
    onSelectChange: setSelected,
    getItemValue: (item) => item.name,
    isItemDisabled: (item) => item.name.length > 10,
    feature: autocomplete(),
    items: items
  });

  // Simulate fetching filtered items
  useEffect(() => {
    if (value) {
      setItems(fruits.filter(f =>
        f.name.toLowerCase().includes(value.toLowerCase())
      ));
    } else {
      setItems(fruits);
    }
  }, [value]);

  return (
    <div>
      <input {...getInputProps()} />
      {open && (
        <ul {...getListProps()}>
          {items.map((item, index) => (
            <li
              key={item.id}
              {...getItemProps({ item, index })}
              aria-disabled={item.name.length > 10}
            >
              {item.name}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}
```

--------------------------------

### Flatten grouped items with mergeGroupedItems

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/api-reference/utilities.md

Examples demonstrating how to flatten different data structures using mergeGroupedItems.

```typescript
const grouped = [
  ['Apple', 'Apricot'],
  ['Banana', 'Blueberry'],
  ['Cherry']
];

const flat = mergeGroupedItems({ groups: grouped });
// Result: ['Apple', 'Apricot', 'Banana', 'Blueberry', 'Cherry']
```

```typescript
const grouped = {
  fruits: ['Apple', 'Banana'],
  veggies: ['Carrot', 'Celery'],
  dairy: ['Cheese', 'Milk']
};

const flat = mergeGroupedItems({ groups: grouped });
// Result: ['Apple', 'Banana', 'Carrot', 'Celery', 'Cheese', 'Milk']
```

```typescript
interface Category {
  name: string;
  items: string[];
}

const grouped: Category[] = [
  { name: 'US States', items: ['California', 'Texas'] },
  { name: 'Countries', items: ['Canada', 'Mexico'] }
];

const flat = mergeGroupedItems({
  groups: grouped,
  getItemsInGroup: (category) => category.items
});
// Result: ['California', 'Texas', 'Canada', 'Mexico']
```

--------------------------------

### Define Feature type and implementation

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/types.md

Defines the generic feature function structure and provides an example implementation.

```typescript
type Feature<T, Yield extends object> = (cx: Contextual<T>) => Yield;
```

```typescript
const myFeature: Feature<User, { getInputProps: () => InputProps }> = (cx) => ({
  getInputProps: () => ({
    onChange: (e) => cx.onChange(e.target.value)
  })
});
```

--------------------------------

### Define object data structure

Source: https://github.com/szhsin/react-autocomplete/blob/master/website/docs/docs/extras/object-items.mdx

Example data structure for object-based list items.

```ts
export const states = [
  { abbr: 'AL', name: 'Alabama' },
  { abbr: 'AK', name: 'Alaska' },
  { abbr: 'AZ', name: 'Arizona' },
  { abbr: 'AR', name: 'Arkansas' },
  { abbr: 'CA', name: 'California' },
  { abbr: 'CO', name: 'Colorado' },
  { abbr: 'CT', name: 'Connecticut' },
  { abbr: 'DE', name: 'Delaware' },
  { abbr: 'FL', name: 'Florida' },
  { abbr: 'GA', name: 'Georgia' },
  { abbr: 'HI', name: 'Hawaii' },
  { abbr: 'ID', name: 'Idaho' },
  { abbr: 'IL', name: 'Illinois' },
  { abbr: 'IN', name: 'Indiana' },
  { abbr: 'IA', name: 'Iowa' },
  { abbr: 'KS', name: 'Kansas' },
  { abbr: 'KY', name: 'Kentucky' },
  { abbr: 'LA', name: 'Louisiana' },
  { abbr: 'ME', name: 'Maine' },
  { abbr: 'MD', name: 'Maryland' },
  { abbr: 'MA', name: 'Massachusetts' },
  { abbr: 'MI', name: 'Michigan' },
  { abbr: 'MN', name: 'Minnesota' },
  { abbr: 'MS', name: 'Mississippi' },
  { abbr: 'MO', name: 'Missouri' },
  { abbr: 'MT', name: 'Montana' },
  { abbr: 'NE', name: 'Nebraska' },
  { abbr: 'NV', name: 'Nevada' },
  { abbr: 'NH', name: 'New Hampshire' },
  { abbr: 'NJ', name: 'New Jersey' },
  { abbr: 'NM', name: 'New Mexico' },
  { abbr: 'NY', name: 'New York' },
  { abbr: 'NC', name: 'North Carolina' },
  { abbr: 'ND', name: 'North Dakota' },
  { abbr: 'OH', name: 'Ohio' },
  { abbr: 'OK', name: 'Oklahoma' },
  { abbr: 'OR', name: 'Oregon' },
  { abbr: 'PA', name: 'Pennsylvania' },
  { abbr: 'RI', name: 'Rhode Island' },
  { abbr: 'SC', name: 'South Carolina' },
  { abbr: 'SD', name: 'South Dakota' },
  { abbr: 'TN', name: 'Tennessee' },
  { abbr: 'TX', name: 'Texas' },
  { abbr: 'UT', name: 'Utah' },
  { abbr: 'VT', name: 'Vermont' },
  { abbr: 'VA', name: 'Virginia' },
  { abbr: 'WA', name: 'Washington' },
  { abbr: 'WV', name: 'West Virginia' },
  { abbr: 'WI', name: 'Wisconsin' },
  { abbr: 'WY', name: 'Wyoming' },
];
```

--------------------------------

### Build static website

Source: https://github.com/szhsin/react-autocomplete/blob/master/website/README.md

Compiles the project into static files located in the build directory for deployment.

```bash
$ npm run build
```

--------------------------------

### Import from Main Entry Point

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/README.md

Use the main package entry point to access primary hooks, pre-built features, and types.

```typescript
import { 
  useCombobox,
  useMultiSelect,
  autocomplete,
  dropdown,
  multiSelect,
  multiSelectDropdown,
  supercomplete,
  autocompleteLite,
  autoFocus,
  // ... more atoms
  mergeGroupedItems,
  mergeModules,
  type ComboboxProps,
  type MultiSelectProps,
  type Feature,
  // ... more types
} from '@szhsin/react-autocomplete';
```

--------------------------------

### View Project Documentation Structure

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/INDEX.md

A visual representation of the file system layout for the project documentation.

```text
output/
├── README.md                          (← START HERE)
├── API-OVERVIEW.md                    Quick reference and patterns
├── INDEX.md                           This file
├── PATTERNS-AND-PRACTICES.md          Advanced patterns and recipes
├── types.md                           Type definitions reference
├── configuration.md                   Configuration options
├── module-structure.md                Architecture and exports
└── api-reference/
    ├── hooks.md                       useCombobox, useMultiSelect
    ├── features.md                    14 features (atoms + molecules)
    └── utilities.md                   mergeGroupedItems, mergeModules
```

--------------------------------

### useCombobox<T, F>

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/README.md

Main entry point hook for creating a combobox component.

```APIDOC
### useCombobox<T, F>

#### Signature
`useCombobox<T, F>(props: ComboboxProps<T, F>) → AutocompleteReturn<T> & F`
```

--------------------------------

### Basic useCombobox Implementation

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/api-reference/hooks.md

A standard implementation of a fruit picker using the useCombobox hook.

```typescript
import { useCombobox, autocomplete } from '@szhsin/react-autocomplete';

type Fruit = { name: string; id: number };
const fruits: Fruit[] = [
  { name: 'Apple', id: 1 },
  { name: 'Banana', id: 2 },
  { name: 'Cherry', id: 3 }
];

function FruitPicker() {
  const [value, setValue] = useState('');
  const [selected, setSelected] = useState<Fruit | undefined>();

  const {
    getInputProps,
    getListProps,
    getItemProps,
    getToggleProps,
    open,
    focusIndex,
    isItemSelected
  } = useCombobox({
    value,
    onChange: setValue,
    selected,
    onSelectChange: setSelected,
    getItemValue: (item) => item.name,
    feature: autocomplete(),
    items: fruits.filter(f => 
      f.name.toLowerCase().includes(value.toLowerCase())
    )
  });

  return (
    <div>
      <input {...getInputProps()} />
      <button {...getToggleProps()}>▼</button>
      {open && (
        <ul {...getListProps()}>
          {fruits.map((item, index) => (
            <li
              key={item.id}
              {...getItemProps({ item, index })}
              style={{ backgroundColor: focusIndex === index ? '#e0e0e0' : '' }}
            >
              {item.name}
            </li>
          ))}
        </ul>
      )}
      {selected && <div>Selected: {selected.name}</div>}
    </div>
  );
}
```

--------------------------------

### Usage of Contextual

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/types.md

Demonstrates how a feature receives the Contextual object as its first parameter.

```typescript
const myFeature = <T>(): Feature<T, MyYield> => (contextual: Contextual<T>) => {
  const { value, items, selected, open, setOpen, getItemValue } = contextual;
  // ...
};
```

--------------------------------

### Prefix Match Filtering

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/PATTERNS-AND-PRACTICES.md

Filters items based on whether their value starts with the search input, suitable for dropdown-style autocomplete.

```typescript
const filteredItems = items.filter(item =>
  getItemValue(item).toLowerCase().startsWith(value.toLowerCase())
);
```

--------------------------------

### Main Entry Point Exports

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/module-structure.md

Defines the public API surface for the library, including hooks, atom/molecule features, utilities, and core types.

```typescript
// Hooks
export { useCombobox } from './hooks/useCombobox';
export { useMultiSelect } from './hooks/useMultiSelect';

// Features - Atom
export { type AutocompleteLiteFeature, autocompleteLite } from './features/atom/autocompleteLite';

// Features - Molecule
export { type AutocompleteFeature, autocomplete } from './features/molecule/autocomplete';
export { type DropdownFeature, dropdown } from './features/molecule/dropdown';
export { type MultiSelectFeature, multiSelect } from './features/molecule/multiSelect';
export { type MultiSelectDropdownFeature, multiSelectDropdown } from './features/molecule/multiSelectDropdown';
export { type SupercompleteFeature, supercomplete } from './features/molecule/supercomplete';

// Utilities
export { mergeGroupedItems } from './utils/mergeGroupedItems';
export { mergeModules } from './utils/mergeModules';

// Types
export type {
  ComboboxProps,
  MultiSelectProps,
  Feature,
  MergedFeature,
  FeatureProps
} from './types';
```

--------------------------------

### Implement a basic combobox

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/API-OVERVIEW.md

A standard implementation using the useCombobox hook and the autocomplete feature.

```typescript
import { useCombobox, autocomplete } from '@szhsin/react-autocomplete';
import { useState } from 'react';

const fruits = ['Apple', 'Banana', 'Cherry'];

function FruitPicker() {
  const [value, setValue] = useState('');
  const [selected, setSelected] = useState<string | undefined>();

  const {
    getInputProps,
    getListProps,
    getItemProps,
    getToggleProps,
    open,
    focusIndex
  } = useCombobox({
    value,
    onChange: setValue,
    selected,
    onSelectChange: setSelected,
    items: fruits.filter(f => f.toLowerCase().includes(value.toLowerCase())),
    feature: autocomplete()
  });

  return (
    <div>
      <label>Fruit:</label>
      <input {...getInputProps()} />
      <button {...getToggleProps()}>▼</button>
      {open && (
        <ul {...getListProps()}>
          {fruits.map((item, index) => (
            <li
              key={item}
              {...getItemProps({ item, index })}
              style={{ backgroundColor: focusIndex === index ? '#e0e0e0' : '' }}
            >
              {item}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}
```

--------------------------------

### useMultiSelect<T, F>

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/README.md

Main entry point hook for creating a multi-select component.

```APIDOC
### useMultiSelect<T, F>

#### Signature
`useMultiSelect<T, F>(props: MultiSelectProps<T, F>) → AutocompleteReturn<T> & F & { removeSelect }`
```

--------------------------------

### Main Entry Point Hooks

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/README.md

Primary hooks for implementing combobox and multi-select functionality.

```typescript
useCombobox<T, F>(props: ComboboxProps<T, F>) 
  → AutocompleteReturn<T> & F
  
useMultiSelect<T, F>(props: MultiSelectProps<T, F>) 
  → AutocompleteReturn<T> & F & { removeSelect }
```

--------------------------------

### Package.json Exports Configuration

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/module-structure.md

Configures module resolution for the package, mapping entry points to their respective CommonJS and ESM distributions.

```json
{
  "exports": {
    ".": {
      "types": "./types/index.d.ts",
      "require": "./dist/cjs/index.cjs",
      "default": "./dist/esm/index.mjs"
    },
    "./features/atom": {
      "types": "./types/features/atom/index.d.ts",
      "require": "./dist/cjs/features/atom/index.cjs",
      "default": "./dist/esm/features/atom/index.mjs"
    },
    "./features/molecule": {
      "types": "./types/features/molecule/index.d.ts",
      "require": "./dist/cjs/features/molecule/index.cjs",
      "default": "./dist/esm/features/molecule/index.mjs"
    }
  }
}
```

--------------------------------

### Create a custom molecule from atoms

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/api-reference/utilities.md

Shows how to wrap multiple features into a reusable function that accepts configuration props.

```typescript
import { mergeModules, autocompleteLite, autoFocus } from '@szhsin/react-autocomplete';

const autocompleteFocus = (props) =>
  mergeModules(
    autocompleteLite(props),
    autoFocus(props)
  );

// Usage
const result = useCombobox({
  feature: autocompleteFocus({
    onRequestItem: (e, res) => {
      const index = items.findIndex(item =>
        item.name.startsWith(e.value)
      );
      if (index >= 0) res({ index, item: items[index] });
    }
  }),
  // ...
});
```

--------------------------------

### Configure Autocomplete Features

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/PATTERNS-AND-PRACTICES.md

Pass configuration objects to feature factories to enable dynamic behavior like custom keyboard shortcuts.

```typescript
type KeyboardShortcutsFeature<T> = Feature<T, Pick<GetProps<T>, 'getInputProps'>>;

const withKeyboardShortcuts = <T>(config: {
  toggleKey?: string;
  clearKey?: string;
}): KeyboardShortcutsFeature<T> => ({ open, setOpen, onChange }) => ({
  getInputProps: () => ({
    onKeyDown: (e) => {
      if (config.toggleKey && e.key === config.toggleKey) {
        setOpen(!open);
      }
      if (config.clearKey && e.key === config.clearKey && e.ctrlKey) {
        onChange('');
      }
    }
  })
});

const advancedAutocomplete = (props) =>
  mergeModules(
    autocomplete(props),
    withKeyboardShortcuts({
      toggleKey: '/',
      clearKey: 'k'
    })
  );
```

--------------------------------

### Memoize Feature Configuration with useMemo

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/PATTERNS-AND-PRACTICES.md

Memoize complex configuration objects and derived features to ensure stable references across renders.

```typescript
const featureConfig = useMemo(() => ({
  rovingText: true,
  closeOnSelect: true
}), []);

const feature = useMemo(() => {
  return autocomplete(featureConfig);
}, [featureConfig]);

useCombobox({
  feature,
  // ...
});
```

--------------------------------

### Usage of GetProps

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/types.md

Demonstrates how to consume prop getters from the useCombobox hook and spread them onto DOM elements.

```typescript
const {
  getInputProps,
  getListProps,
  getItemProps
} = useCombobox({
  feature: autocomplete(),
  // ...
});

// Spread onto DOM elements
<input {...getInputProps()} />
<ul {...getListProps()}>
  {items.map((item, index) => (
    <li {...getItemProps({ item, index })}>{item.name}</li>
  ))}
</ul>
```

--------------------------------

### Virtualize Autocomplete List with @tanstack/react-virtual

Source: https://github.com/szhsin/react-autocomplete/blob/master/website/docs/docs/extras/virtualization.mdx

Integrates virtualization to efficiently render a large list of 10,000 items within the autocomplete component.

```tsx
import CodeBlock from '@theme/CodeBlock';

import sourceCode from '!!raw-loader!@site/src/components/Virtualization/CodeBlock';
import { Virtualization } from '@site/src/components/Virtualization';

# Virtualization

Here’s an example of integrating [@tanstack/react-virtual](https://tanstack.com/virtual/latest/docs/introduction) to virtualize an autocomplete list with 10,000 items.

<Virtualization />

<CodeBlock language="tsx">{sourceCode}</CodeBlock>
```

--------------------------------

### useCombobox(config)

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/configuration.md

The useCombobox hook accepts a configuration object to manage autocomplete and dropdown behavior. Below are the available configuration properties.

```APIDOC
## useCombobox(config)

### Description
Configures the behavior of the combobox component, including data source, selection logic, and item interaction.

### Parameters
- **value** (string | undefined) - Required - Current input value.
- **onChange** ((value?: string) => void) - Required - Callback when user types.
- **items** (T[]) - Required - Array of items to display.
- **feature** (Feature<T, FeatureYield>) - Required - Feature function (e.g., autocomplete(), dropdown()).
- **getItemValue** ((item: T) => string) - Optional - Converts item to display string (Required if T is not string).
- **selected** (T | undefined) - Optional - Currently selected item.
- **onSelectChange** ((item?: T) => void) - Optional - Callback when selection changes.
- **isEqual** ((a?: T, b?: T) => boolean) - Optional - Custom equality function for item comparison.
- **flipOnSelect** (boolean) - Optional - If true, selecting same item again deselects it.
- **isItemDisabled** ((item: T) => boolean) - Optional - Returns true if item should be skipped.
- **isItemAction** ((item: T) => boolean) - Optional - Returns true if item triggers onAction.
- **onAction** ((item: T) => void) - Optional - Callback when action item is clicked.
- **inputRef** (React.RefObject<HTMLInputElement | null>) - Optional - External input element reference.
```

--------------------------------

### Test Autocomplete with React Testing Library

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/PATTERNS-AND-PRACTICES.md

Use user-event to simulate typing and keyboard navigation to verify filtering and selection logic.

```typescript
import { render, screen, fireEvent } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

test('autocomplete filters items', async () => {
  render(<AutocompleteComponent />);
  
  const input = screen.getByRole('combobox');
  
  // Type to filter
  await userEvent.type(input, 'ban');
  
  // Check filtered items appear
  expect(screen.getByText('Banana')).toBeInTheDocument();
  expect(screen.queryByText('Apple')).not.toBeInTheDocument();
});

test('keyboard navigation works', async () => {
  render(<AutocompleteComponent />);
  
  const input = screen.getByRole('combobox');
  const list = screen.getByRole('listbox');
  
  // Open list
  await userEvent.click(input);
  expect(list).toBeVisible();
  
  // Navigate with arrow keys
  await userEvent.keyboard('{ArrowDown}');
  const firstItem = screen.getAllByRole('option')[0];
  expect(firstItem).toHaveAttribute('aria-selected', 'true');
  
  await userEvent.keyboard('{ArrowDown}');
  const secondItem = screen.getAllByRole('option')[1];
  expect(secondItem).toHaveAttribute('aria-selected', 'true');
  
  // Select with Enter
  await userEvent.keyboard('{Enter}');
  expect(list).not.toBeVisible();
});
```

--------------------------------

### Configure Search vs Select Mode

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/PATTERNS-AND-PRACTICES.md

Toggles between independent input behavior and synchronized selection behavior.

```typescript
// Search mode
feature: autocomplete()  // select: false

// Select mode
feature: dropdown()  // select: true internally
```

--------------------------------

### Define Peer Dependencies

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/module-structure.md

Specifies the required React version for the project in package.json.

```json
{
  "peerDependencies": {
    "react": "^16.8 || ^17 || ^18 || ^19"
  }
}
```

--------------------------------

### Implement Virtualized Autocomplete with react-window

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/PATTERNS-AND-PRACTICES.md

Uses FixedSizeList to render only visible items in the autocomplete dropdown. Requires react-window and the useCombobox hook.

```typescript
import { FixedSizeList as List } from 'react-window';

function VirtualizedAutocomplete() {
  const [value, setValue] = useState('');
  const [selected, setSelected] = useState<Item | undefined>();

  const filteredItems = items.filter(item =>
    item.name.toLowerCase().includes(value.toLowerCase())
  );

  const {
    getInputProps,
    getListProps,
    getItemProps,
    open,
    focusIndex
  } = useCombobox({
    value,
    onChange: setValue,
    selected,
    onSelectChange: setSelected,
    items: filteredItems,
    feature: autocomplete()
  });

  return (
    <div>
      <input {...getInputProps()} />
      
      {open && (
        <div {...getListProps()} style={{ height: '300px', width: '100%' }}>
          <List
            height={300}
            itemCount={filteredItems.length}
            itemSize={35}
            width="100%"
          >
            {({ index, style }) => {
              const item = filteredItems[index];
              return (
                <div
                  key={item.id}
                  {...getItemProps({ item, index })}
                  style={{
                    ...style,
                    backgroundColor: focusIndex === index ? '#f0f0f0' : 'white',
                    padding: '8px'
                  }}
                >
                  {item.name}
                </div>
              );
            }}
          </List>
        </div>
      )}
    </div>
  );
}
```

--------------------------------

### Basic multi-select configuration

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/configuration.md

Standard implementation of the useMultiSelect hook with basic item selection and filtering.

```typescript
const config = {
  value: tagInput,
  onChange: setTagInput,
  items: allTags,
  selected: selectedTags,
  onSelectChange: setSelectedTags,
  getItemValue: (tag) => tag.name,
  feature: multiSelect()
};

useMultiSelect(config);
```

--------------------------------

### Action Items Implementation

Source: https://github.com/szhsin/react-autocomplete/blob/master/website/docs/docs/extras/action-items.mdx

The component definition and data structure for handling action items in the autocomplete list.

```tsx
import React from 'react';
import { Autocomplete } from '@szhsin/react-autocomplete';

export const ActionItems = () => {
  return (
    <Autocomplete
      items={['Apple', 'Banana', 'Cherry']}
      onAction={(item) => console.log('Action triggered:', item)}
    />
  );
};
```

```ts
export const fruits = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'];
```

--------------------------------

### Import Atom Features

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/README.md

Import tree-shakeable atom features for granular control and composition.

```typescript
import { 
  autocompleteLite,
  label,
  inputToggle,
  // ... other atoms
  type AutocompleteLiteFeature,
  type LabelFeature
} from '@szhsin/react-autocomplete/features/atom';
```

--------------------------------

### Integrate Floating UI with Autocomplete

Source: https://github.com/szhsin/react-autocomplete/blob/master/website/docs/docs/extras/floating-ui.mdx

Implementation of an autocomplete component using Floating UI for dynamic positioning.

```tsx
import React, { useState } from 'react';
import { useFloating, flip, shift, size } from '@floating-ui/react';
import { Autocomplete } from 'react-autocomplete';
import states from './data/states';

export default function AutocompleteWithFloatingUI() {
  const [value, setValue] = useState('');
  const { refs, floatingStyles, middlewareData } = useFloating({
    middleware: [
      flip(),
      shift(),
      size({
        apply({ rects, elements }) {
          Object.assign(elements.floating.style, {
            maxHeight: `${window.innerHeight - rects.reference.bottom - 20}px`,
          });
        },
      }),
    ],
  });

  return (
    <Autocomplete
      ref={refs.setReference}
      value={value}
      onChange={setValue}
      options={states}
      floatingProps={{
        ref: refs.setFloating,
        style: floatingStyles,
      }}
    />
  );
}
```

--------------------------------

### useCombobox

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/module-structure.md

The primary hook for implementing single-select autocomplete functionality.

```APIDOC
## useCombobox

### Description
Main hook for single-select autocomplete functionality.

### Signature
`<T, F>(props: ComboboxProps<T, F>) => AutocompleteReturn<T> & F`
```

--------------------------------

### Bind props to DOM elements

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/API-OVERVIEW.md

Demonstrates how to spread the object returned by a props method onto a DOM element.

```typescript
const { getInputProps } = useCombobox({ /* ... */ });
<input {...getInputProps()} />  // ← Spreads { type, role, onChange, ... }
```

--------------------------------

### multiInput

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/api-reference/features.md

Enables multi-select tag display with keyboard navigation for tags. Must be used with useMultiSelect hook.

```APIDOC
## multiInput

### Signature
`const multiInput = <T>(): MultiInputFeature<T>`

### Returns
- **isInputActive** (boolean)
- **isTagActive** (Function) - Returns boolean
- **getInputProps** (Function) - Returns Partial<InputHTMLAttributes>
```

--------------------------------

### Integrate Floating UI with Dropdown

Source: https://github.com/szhsin/react-autocomplete/blob/master/website/docs/docs/extras/floating-ui.mdx

Implementation of a dropdown component using Floating UI for dynamic positioning.

```tsx
import React, { useState } from 'react';
import { useFloating, flip, shift, size } from '@floating-ui/react';
import { Dropdown } from 'react-autocomplete';
import states from './data/states';

export default function DropdownWithFloatingUI() {
  const [value, setValue] = useState('');
  const { refs, floatingStyles } = useFloating({
    middleware: [
      flip(),
      shift(),
      size({
        apply({ rects, elements }) {
          Object.assign(elements.floating.style, {
            maxHeight: `${window.innerHeight - rects.reference.bottom - 20}px`,
          });
        },
      }),
    ],
  });

  return (
    <Dropdown
      ref={refs.setReference}
      value={value}
      onChange={setValue}
      options={states}
      floatingProps={{
        ref: refs.setFloating,
        style: floatingStyles,
      }}
    />
  );
}
```

--------------------------------

### Extend Autocomplete with Simple Features

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/PATTERNS-AND-PRACTICES.md

Create custom features by implementing the Feature interface and merging them with the base autocomplete module.

```typescript
import { mergeModules, autocomplete, Feature, GetProps } from '@szhsin/react-autocomplete';

// Custom feature that adds a help button
type HelpFeature<T> = Feature<T, Pick<GetProps<T>, 'getInputProps'>>;

const withHelp = <T>(): HelpFeature<T> => ({ open, setOpen }) => ({
  getInputProps: () => ({
    onKeyDown: (e) => {
      if (e.key === '?') {
        showHelpDialog();
      }
    }
  })
});

const customAutocomplete = (props) => 
  mergeModules(
    autocomplete(props),
    withHelp()
  );

useCombobox({
  feature: customAutocomplete(),
  // ...
});
```

--------------------------------

### Combine built-in atoms with mergeModules

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/api-reference/utilities.md

Demonstrates merging multiple pre-defined features into a single custom autocomplete configuration.

```typescript
import { mergeModules, autocompleteLite, label, inputToggle } from '@szhsin/react-autocomplete';

const customAutocomplete = mergeModules(
  autocompleteLite({ rovingText: true }),
  label(),
  inputToggle()
);

const { getInputProps, getLabelProps, getToggleProps } = useCombobox({
  feature: customAutocomplete,
  // ...
});
```

--------------------------------

### Default Focus Index

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/configuration.md

Initial focus index setting for the combobox.

```typescript
const defaultFocusIndex = -1;  // No item initially focused
```

--------------------------------

### Usage of Equality

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/types.md

Shows how to provide a custom equality function to the useCombobox hook.

```typescript
type User = { id: number; name: string };

useCombobox({
  items: users,
  selected: currentUser,
  // Compare by ID instead of reference
  isEqual: (a, b) => a?.id === b?.id,
  // ...
});
```

--------------------------------

### Configure autocompleteLite

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/api-reference/features.md

The signature for the autocompleteLite feature configuration.

```typescript
const autocompleteLite = <T>({
  select,
  rovingText = !select,
  deselectOnClear = true,
  deselectOnChange = true,
  closeOnSelect = true
}: AutocompleteFeatureProps<T> = {}): AutocompleteLiteFeature<T>
```

--------------------------------

### Configure dropdown select

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/configuration.md

Configures the hook to behave as a dropdown menu using the dropdown feature.

```typescript
const config = {
  value: selectedColor,
  onChange: setSelectedColor,
  selected: selectedColor,
  onSelectChange: setSelectedColor,
  items: ['Red', 'Green', 'Blue'],
  feature: dropdown({ closeOnSelect: true })
};

useCombobox(config);
```

--------------------------------

### Implement multiInput feature in a component

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/api-reference/features.md

Shows how to use the multiInput feature with the useMultiSelect hook.

```typescript
const {
  getInputProps,
  isInputActive,
  isTagActive
} = useMultiSelect({
  feature: multiSelect(),
  // ...
});

return (
  <div>
    {selected.map(tag => (
      <span
        key={tag.id}
        style={{ backgroundColor: isTagActive(tag) ? '#007bff' : '#e9ecef' }}
      >
        {tag.label}
      </span>
    ))}
    <input {...getInputProps()} />
  </div>
);
```

--------------------------------

### Compose with custom features

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/api-reference/utilities.md

Illustrates combining a standard library feature with a custom-defined feature object.

```typescript
import { mergeModules, Feature, GetProps } from '@szhsin/react-autocomplete';

// Custom feature for keyboard shortcuts
type KeyboardShortcutsFeature<T> = Feature<T, Pick<GetProps<T>, 'getInputProps'>>;

const keyboardShortcuts = (): KeyboardShortcutsFeature<any> =>
  ({ setOpen, open }) => ({
    getInputProps: () => ({
      onKeyDown: (e) => {
        if (e.key === '/') {
          setOpen(!open);
        }
        if (e.key === 'c' && e.ctrlKey) {
          // Clear input
        }
      }
    })
  });

// Combine with standard autocomplete
const advancedAutocomplete = mergeModules(
  autocomplete(),
  keyboardShortcuts()
);

const { getInputProps } = useCombobox({
  feature: advancedAutocomplete,
  // ...
});
```

--------------------------------

### Build progressive feature sets

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/api-reference/utilities.md

Shows how to incrementally build complex feature sets by merging existing feature variables.

```typescript
import { mergeModules, autocompleteLite, label } from '@szhsin/react-autocomplete';

// Start simple
const basic = autocompleteLite();

// Add label support
const withLabel = mergeModules(
  basic,
  label()
);

// Switch to more complex
const advanced = mergeModules(
  withLabel,
  autoFocus({ onRequestItem: myCallback })
);
```

--------------------------------

### Configure autocomplete with action items

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/configuration.md

Defines items that trigger custom actions instead of selection using isItemAction and onAction.

```typescript
const config = {
  value,
  onChange: setValue,
  items: [...filteredUsers, { id: 'new', name: '+ Create New User' }],
  selected,
  onSelectChange: setSelected,
  getItemValue: (item) => item.name,
  isItemAction: (item) => item.id === 'new',
  onAction: (item) => {
    if (item.id === 'new') {
      openCreateDialog();
    }
  },
  feature: autocomplete()
};

useCombobox(config);
```

--------------------------------

### Defining Action Items

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/PATTERNS-AND-PRACTICES.md

Use isItemAction and onAction to distinguish non-selectable items that trigger specific application behaviors.

```typescript
const baseItems = users;
const itemsWithAction = [...baseItems, { id: 'new', name: '+ Create New User' }];

const { getItemProps } = useCombobox({
  items: itemsWithAction,
  isItemAction: (item) => item.id === 'new',
  onAction: (item) => {
    if (item.id === 'new') {
      openCreateUserDialog();
    }
  },
  feature: autocomplete()
});
```

--------------------------------

### Props Methods

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/API-OVERVIEW.md

Methods returned by hooks to bind accessibility attributes to DOM elements.

```APIDOC
## Props Methods

### Description
Methods returned by hooks that should be spread onto their respective DOM elements to provide necessary accessibility attributes.

### Methods
- **getInputProps()** - Returns attributes for `<input>` elements.
- **getListProps()** - Returns attributes for `<ul>` or list container elements.
- **getItemProps()** - Returns attributes for `<li>` or item container elements.
- **getToggleProps()** - Returns attributes for toggle `<button>` elements.
- **getClearProps()** - Returns attributes for clear `<button>` elements.
- **getLabelProps()** - Returns attributes for `<label>` elements.
- **getFocusCaptureProps()** - Returns attributes for focus-trap container elements.
```

--------------------------------

### MultiSelect Component Implementation

Source: https://github.com/szhsin/react-autocomplete/blob/master/website/docs/docs/features/multiSelect.mdx

The core component logic for handling multiple selections.

```tsx
import sourceCode from '!!raw-loader!@site/src/components/MultiSelect/CodeBlock';
```

--------------------------------

### Implement dropdownToggle in a component

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/api-reference/features.md

Shows how to integrate the dropdownToggle feature within a useCombobox hook.

```typescript
import { useCombobox, autocomplete } from '@szhsin/react-autocomplete';

function DropdownAutocomplete() {
  const {
    getInputProps,
    getListProps,
    getItemProps,
    getToggleProps
  } = useCombobox({
    value,
    onChange: setValue,
    feature: autocomplete(),  // Contains dropdownToggle internally
    items: fruits
  });

  return (
    <div style={{ position: 'relative' }}>
      <input {...getInputProps()} />
      <button {...getToggleProps()}>▼</button>
      {/* list */}
    </div>
  );
}
```

--------------------------------

### supercomplete<T>(props: Pick<FeatureProps<T>, 'onRequestItem' | 'select' | 'deselectOnClear' | 'deselectOnChange' | 'closeOnSelect'>)

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/api-reference/features.md

Provides both inline autocomplete and full autocomplete suggestions.

```APIDOC
## supercomplete<T>

### Description
Provides both inline autocomplete and full autocomplete suggestions.

### Signature
`const supercomplete = <T>(props: Pick<FeatureProps<T>, 'onRequestItem' | 'select' | 'deselectOnClear' | 'deselectOnChange' | 'closeOnSelect'>): SupercompleteFeature<T>`

### Required Configuration
- **onRequestItem** (function) - Callback for requesting matched items: `(event: { value: string }, res: (data: { index: number; item: T }) => void) => void`
```

--------------------------------

### Combine features with createCustomFeature

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/api-reference/utilities.md

Dynamically constructs a feature set based on a configuration object using mergeModules.

```typescript
function createCustomFeature<T>(config: {
  hasLabel: boolean;
  hasToggle: boolean;
  isMultiSelect: boolean;
}) {
  const features = [
    autocompleteLite({ select: config.isMultiSelect })
  ];
  
  if (config.hasLabel) {
    features.push(label());
  }
  
  if (config.hasToggle) {
    features.push(inputToggle());
  }
  
  return mergeModules(...features);
}

// Usage
const feature = createCustomFeature({
  hasLabel: true,
  hasToggle: true,
  isMultiSelect: false
});
```

--------------------------------

### useMultiSelect(config)

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/configuration.md

The useMultiSelect hook configuration object defines how the multi-select component behaves, including data filtering, selection callbacks, and item interaction logic.

```APIDOC
## useMultiSelect Configuration

### Description
The `useMultiSelect` hook is used to manage multi-selection state within a React component. It accepts a configuration object to define data sources, selection behavior, and event callbacks.

### Parameters
- **value** (string | undefined) - Required - Current input value for filtering.
- **onChange** ((value?: string) => void) - Required - Callback when user types in input.
- **items** (T[]) - Required - Items available for selection.
- **selected** (T[]) - Required - Currently selected items array.
- **feature** (Feature<T, FeatureYield>) - Required - Feature function (typically `multiSelect()` or `multiSelectDropdown()`).
- **getItemValue** ((item: T) => string) - Required if T is not string - Converts item to string.
- **onSelectChange** ((items: T[]) => void) - Optional - Callback when selection array changes.
- **isEqual** ((a?: T, b?: T) => boolean) - Optional - Custom comparison function (defaults to reference equality).
- **flipOnSelect** (boolean) - Optional - If true, selecting same item again removes it (default: false).
- **isItemDisabled** ((item: T) => boolean) - Optional - Skips item in navigation if returns true.
- **isItemAction** ((item: T) => boolean) - Optional - Treats item as action if returns true.
- **onAction** ((item: T) => void) - Optional - Called when action item selected.
- **inputRef** (React.RefObject<HTMLInputElement | null>) - Optional - External input ref.
```

--------------------------------

### inputFocus

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/api-reference/features.md

Tracks whether the input is focused or blurred.

```APIDOC
## inputFocus

### Signature
`const inputFocus = <T>(): InputFocusFeature<T>`

### Returns
- **focused** (boolean)
- **getInputProps** (Function) - Returns Partial<InputHTMLAttributes>
```

--------------------------------

### Import Molecule Features

Source: https://github.com/szhsin/react-autocomplete/blob/master/_autodocs/README.md

Import tree-shakeable molecule features for higher-level functionality.

```typescript
import { 
  autocomplete,
  dropdown,
  multiSelect,
  // ... other molecules
  type AutocompleteFeature,
  type DropdownFeature
} from '@szhsin/react-autocomplete/features/molecule';
```
Tokens:
Raw