# Autocomplete

Campo que sugere enquanto se digita, e aceita o que não esta na lista.

**O painel e o mesmo do Combobox.** Use `ComboboxContent`, `ComboboxList` e
`ComboboxItem` dentro dele; só o campo troca, para `AutocompleteInput`.

```tsx
<Autocomplete items={CIDADES}>
  <AutocompleteInput placeholder="Cidade" />
  <ComboboxContent emptyMessage="Nenhuma cidade com esse nome.">
    <ComboboxList>
      {(cidade: string) => (
        <ComboboxItem key={cidade} value={cidade}>
          {cidade}
        </ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Autocomplete>
```

## Quando não usar

Quando o valor **tem que** ser uma das opções (o cliente da nota, a conta
contábil, a unidade de medida), use `Combobox`. É essa a diferença entre os
dois: lá a lista manda, aqui a sugestão ajuda e o texto livre vale. Deixar
passar "Clínica São Lucaz" num campo que devia apontar para um cadastro é um
erro que só aparece no relatório do mês seguinte.

## No React Native

No React Native quem cobre este caso é o `Combobox`, com uma perda que precisa entrar na sua decisão: ele **não aceita valor fora da lista**. O que o `Autocomplete` tem de próprio, que é deixar a pessoa escrever o que não está cadastrado, não existe lá. Se o campo precisa aceitar o inédito, no celular ele é um `Input` seu com sugestões, e não esta peça.

## Importação

```tsx
import { Autocomplete } from '@rivocode/ui'
```

## Exemplos

### Busca com texto livre

```tsx
import {
  Autocomplete,
  AutocompleteInput,
  ComboboxContent,
  ComboboxItem,
  ComboboxList,
} from '@rivocode/ui'

const CIDADES = ['Joao Pessoa', 'Campina Grande', 'Cabedelo', 'Bayeux', 'Patos']

export function FreeTextSearch() {
  return (
    <div className="min-h-64 w-80">
      <Autocomplete items={CIDADES} defaultOpen>
        <AutocompleteInput aria-label="Cidade" placeholder="Cidade" />
        <ComboboxContent emptyMessage="Nenhuma cidade com esse nome.">
          <ComboboxList>
            {(cidade: string) => (
              <ComboboxItem key={cidade} value={cidade}>
                {cidade}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Autocomplete>
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Desde | O que faz |
| --- | --- | --- | --- | --- |
| `items` | `Items` | sim | 0.4.0 | The items to be displayed in the list. |
| `actionsRef` | `RefObject<AutocompleteRootActions \| null>` |  | 0.4.0 | A ref to imperative actions. |
| `autoHighlight` | `"always" \| boolean` |  | 0.4.0 | Whether the first matching item is highlighted automatically. |
| `defaultOpen` | `boolean` |  | 0.4.0 | Whether the popup is initially open. |
| `defaultValue` | `string \| number \| readonly string[]` |  | 0.4.0 | The uncontrolled input value of the autocomplete when it's initially rendered. |
| `disabled` | `boolean` |  | 0.4.0 | Whether the component should ignore user interaction. |
| `filter` | `((itemValue: Items[number]["items"][number], query: string, itemToString?: ((itemValue: Items[number]["items"][number]) => string) \| undefined) => boolean) \| null` |  | 0.4.0 | Filter function used to match items vs input query. |
| `filteredItems` | `readonly any[] \| readonly Group<any>[]` |  | 0.4.0 | Filtered items to display in the list. |
| `form` | `string` |  | 0.4.0 | Identifies the form that owns the internal input. |
| `grid` | `boolean` |  | 0.4.0 | Whether list items are presented in a grid layout. |
| `highlightItemOnHover` | `boolean` |  | 0.4.0 | Whether moving the pointer over items should highlight them. |
| `inline` | `boolean` |  | 0.4.0 | Whether the list is rendered inline without using the component's own popup. |
| `inputRef` | `Ref<HTMLInputElement>` |  | 0.4.0 | A ref to the hidden input element. |
| `itemToStringValue` | `((itemValue: Items[number]["items"][number]) => string)` |  | 0.4.0 | When the item values are objects (`<Autocomplete.Item value={object}>`), this function converts the object value to a string representation for both display in the input and form submission. |
| `keepHighlight` | `boolean` |  | 0.4.0 | Whether the highlighted item should be preserved when the pointer leaves the list. |
| `limit` | `number` |  | 0.4.0 | The maximum number of items to display in the list. |
| `locale` | `LocalesArgument` |  | 0.4.0 | The locale to use for string comparison. |
| `loopFocus` | `boolean` |  | 0.4.0 | Whether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. |
| `modal` | `boolean` |  | 0.4.0 | Determines if the popup enters a modal state when open. |
| `mode` | `"both" \| "inline" \| "list" \| "none"` |  | 0.4.0 | Controls how the autocomplete behaves with respect to list filtering and inline autocompletion. |
| `name` | `string` |  | 0.4.0 | Identifies the field when a form is submitted. |
| `onItemHighlighted` | `((highlightedValue: Items[number]["items"][number] \| undefined, eventDetails: HighlightEventDetails) => void)` |  | 0.4.0 | Callback fired when an item is highlighted or unhighlighted. |
| `onOpenChange` | `((open: boolean, eventDetails: ChangeEventDetails) => void)` |  | 0.4.0 | Event handler called when the popup is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` |  | 0.4.0 | Event handler called after any animations complete when the popup is opened or closed. |
| `onValueChange` | `((value: string, eventDetails: ChangeEventDetails) => void)` |  | 0.4.0 | Event handler called when the input value of the autocomplete changes. |
| `open` | `boolean` |  | 0.4.0 | Whether the popup is currently open. |
| `openOnInputClick` | `boolean` |  | 0.4.0 | Whether the popup opens when clicking the input. |
| `readOnly` | `boolean` |  | 0.4.0 | Whether the user should be unable to choose a different option from the popup. |
| `required` | `boolean` |  | 0.4.0 | Whether the user must choose a value before submitting a form. |
| `submitOnItemClick` | `boolean` |  | 0.4.0 | Whether clicking an item should submit the autocomplete's owning form. |
| `value` | `string \| number \| readonly string[]` |  | 0.4.0 | The input value of the autocomplete. |
| `virtualized` | `boolean` |  | 0.4.0 | Whether the items are being externally virtualized. |

## Ver também

- [Calendar](/componentes/calendar.md)
- [Checkbox](/componentes/checkbox.md)
- [CheckboxGroup](/componentes/checkbox-group.md)
- [ColorPicker](/componentes/color-picker.md)
- [Combobox](/componentes/combobox.md)
- [DatePicker](/componentes/date-picker.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)