Formulário

Autocomplete

/componentes/autocomplete.mdmarkdown cru, para quem lê com agent em vez de olho

Busca com texto livre

Importar

import { Autocomplete } from '@rivocode/ui'

Quando usar

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.

<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.

API

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

Quando usar

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.

<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

No React Native

API

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