# useTypeahead

Provides a matching callback that can be used to focus an item as
the user types, often used in tandem with
`useListNavigation(){:js}`.

```js
import {useTypeahead} from '@floating-ui/react';
```

See [`FloatingList`](/docs/FloatingList) for creating composable
children API components.

## Usage

This hook is an interaction hook that returns event handler
props.

To use it, pass it the `context{:.const}` object returned from
`useFloating(){:js}`, and then feed its result into the
`useInteractions(){:js}` array. The returned prop getters are
then spread onto the elements for rendering.

`useListNavigation(){:js}` is responsible for synchronizing the
index for focus.

```js /context/
function App() {
  const [activeIndex, setActiveIndex] = useState(null);

  const {refs, floatingStyles, context} = useFloating({
    open: true,
  });

  const items = ['one', 'two', 'three'];

  const listRef = useRef(items);

  const typeahead = useTypeahead(context, {
    listRef,
    activeIndex,
    onMatch: setActiveIndex,
  });

  const {getReferenceProps, getFloatingProps, getItemProps} =
    useInteractions([typeahead]);

  return (
    <>
      <div ref={refs.setReference} {...getReferenceProps()}>
        Reference element
      </div>
      <div
        ref={refs.setFloating}
        style={floatingStyles}
        {...getFloatingProps()}
      >
        {items.map((item, index) => (
          <div
            key={item}
            // Make these elements focusable using a roving tabIndex.
            tabIndex={activeIndex === index ? 0 : -1}
            {...getItemProps()}
          >
            {item}
          </div>
        ))}
      </div>
    </>
  );
}
```

## Props

```ts
interface Props {
  listRef: React.MutableRefObject<Array<string | null>>;
  activeIndex: number | null;
  onMatch?: (index: number) => void;
  enabled?: boolean;
  findMatch?:
    | null
    | ((
        list: Array<string | null>,
        typedString: string
      ) => string | null | undefined);
  resetMs?: number;
  ignoreKeys?: Array<string>;
  selectedIndex?: number | null;
  onTypingChange?: (isTyping) => void;
}
```

### listRef

<Required />

default: empty list

A ref which contains an array of strings whose indices match the
HTML elements of the list.

```js
const listRef = useRef(['one', 'two', 'three']);

useTypeahead(context, {
  listRef,
});
```

You can derive these strings when assigning the node if the
strings are not available up front:

```js
// Array<HTMLElement | null> for `useListNavigation`
const listItemsRef = useRef([]);
// Array<string | null> for `useTypeahead`
const listContentRef = useRef([]);
```

```js {4}
<li
  ref={(node) => {
    listItemsRef.current[index] = node;
    listContentRef.current[index] = node?.textContent ?? null;
  }}
/>
```

Disabled items can be represented by `null{:js}` values in the
array at the relevant index, and will be skipped.

### activeIndex

<Required />

default: `null{:js}`

The currently active index. This specifies where the typeahead
starts.

```js
const [activeIndex, setActiveIndex] = useState(null);

useTypeahead(context, {
  activeIndex,
});
```

### onMatch

default: no-op

Callback invoked with the matching index if found as the user
types.

```js
const [isOpen, setIsOpen] = useState(false);
const [activeIndex, setActiveIndex] = useState(null);
const [selectedIndex, setSelectedIndex] = useState(null);

useTypeahead(context, {
  onMatch: isOpen ? setActiveIndex : setSelectedIndex,
});
```

### enabled

default: `true{:js}`

Conditionally enable/disable the hook.

```js
useTypeahead(context, {
  enabled: false,
});
```

### findMatch

default: lowercase finder

If you'd like to implement custom finding logic (for example
[fuzzy search](https://fusejs.io/)), you can use this callback.

```js
useTypeahead(context, {
  findMatch: (list, typedString) =>
    list.find(
      (itemString) =>
        itemString?.toLowerCase().indexOf(typedString) === 0
    ),
});
```

### resetMs

default: `750{:js}`

Debounce timeout which will reset the transient string as the
user types.

```js
useTypeahead(context, {
  resetMs: 500,
});
```

### ignoreKeys

default: `[]{:js}`

Optional keys to ignore.

```js
useTypeahead(context, {
  ignoreKeys: ['I', 'G', 'N', 'O', 'R', 'E'],
});
```

### selectedIndex

default: `null{:js}`

The currently selected index, if available.

```js
const [selectedIndex, setSelectedIndex] = useState(null);

useTypeahead(context, {
  selectedIndex,
});
```

### onTypingChange

default: no-op

Callback invoked with the typing state as the user types.

```js
useTypeahead(context, {
  onTypingChange(isTyping) {
    // ...
  },
});
```
