O autocompletar é uma entrada de texto normal aprimorada por um painel de opções sugeridas.
Essa ferramenta é útil para configurar os valores de um campo de texto quando em um dos dois cenários abaixo: 1. O valor para a caixa de texto deve ser escolhido a partir de um conjunto pré-definido de valores permitidos, por exemplo, um campo de localização deve conter um nome de localização válido: [caixa de combinação](#combo-box). 2. A caixa de texto pode conter qualquer valor arbitrário, mas é mais vantajosa, porque pode sugerir possíveis valores para o usuário, por exemplo, um campo de pesquisa que pode sugerir pesquisas anteriores ou semelhantes para economizar o tempo do usuário: [free solo](#free-solo). A ideia dessa ferramenta é ser uma versão melhorada das bibliotecas "react-select" e "downshift". ## Caixa de combinação O valor deve ser escolhido a partir de um conjunto predefinido de valores permitidos. {{"demo": "pages/components/autocomplete/ComboBox.js"}} ### Área de exemplos Cada um dos exemplos a seguir demonstra uma funcionalidade do componente Autocomplete. {{"demo": "pages/components/autocomplete/Playground.js"}} ### Seleção de países Escolha um dos 248 países. {{"demo": "pages/components/autocomplete/CountrySelect.js"}} ### Estados controláveis O componente tem dois estados que podem ser controlados: 1. o estado "value" com a combinação das propriedades `value`/`onChange`. Esse estado representa o valor selecionado pelo usuário, por exemplo, quando é pressionado a tecla Enter. 2. o estado "input value" com a combinação das propriedades `inputValue`/`onInputChange`. Esse estado representa o valor exibido na caixa de texto. > ⚠️ Esses dois estados estão isolados, eles podem ser controlados de forma independente. {{"demo": "pages/components/autocomplete/ControllableStates.js"}} ## Free solo Coloque `freeSolo` como true para que o campo de texto contenha qualquer valor aleatório. ### Campo search A propriedade foi desenvolvida para suprir a situação de uso mais comum de um **campo do tipo search** com sugestões, por exemplo, pesquisa do Google ou react-autowhatever. {{"demo": "pages/components/autocomplete/FreeSolo.js"}} ### Creatable Se você pretende usar este modo para uma [caixa de combinação](#combo-box), por experiência (uma versão aprimorada de um elemento select) recomendamos a configuração: - `selectOnFocus` para ajudar o usuário a limpar o valor selecionado. - `clearOnBlur` para ajudar o usuário a digitar um novo valor. - `handleHomeEndKeys` para mover o foco dentro do popup com as teclas Home e End. - Adicione uma última opção para indicar a possibilidade de adição, por exemplo `Adicionar "SUA PESQUISA"`. {{"demo": "pages/components/autocomplete/FreeSoloCreateOption.js"}} Você pode também exibir um diálogo quando o usuário quiser adicionar um novo valor. {{"demo": "pages/components/autocomplete/FreeSoloCreateOptionDialog.js"}} ## Agrupamento {{"demo": "pages/components/autocomplete/Grouped.js"}} ## Opções desabilitadas {{"demo": "pages/components/autocomplete/DisabledOptions.js"}} ## `useAutocomplete` Para casos de customização avançada, nós expomos o hook `useAutocomplete()`. Ele aceita quase as mesmas opções do componente autocompletar exceto todas as propriedades relacionadas a renderização do JSX. O componente autocompletar usa esse hook internamente. ```jsx import useAutocomplete from '@material-ui/lab/useAutocomplete'; ``` - 📦 [4.5 kB gzipado](/size-snapshot). {{"demo": "pages/components/autocomplete/UseAutocomplete.js", "defaultCodeOpen": false}} ### Hook customizado {{"demo": "pages/components/autocomplete/CustomizedHook.js"}} Indo para a seção de [Autocompletar customizado](#customized-autocomplete) vemos um exemplo de customização com o componente `Autocomplete` ao invés do hook. ## Requisições assíncronas {{"demo": "pages/components/autocomplete/Asynchronous.js"}} ### Lugares com a API do Google Maps Uma customização de UI para o autocompletar de lugares do Google Maps. {{"demo": "pages/components/autocomplete/GoogleMaps.js"}} Para esse exemplo, nós precisamos carregar a API de Javascript do [Google Maps](https://developers.google.com/maps/documentation/javascript/tutorial). > ⚠️ Antes de você começar a usar a API JavaScript do Google Maps você precisará estar cadastrado e ter uma conta. ## Múltiplos valores Também conhecidos como tags, o usuário pode inserir mais de um valor. {{"demo": "pages/components/autocomplete/Tags.js"}} ### Opções fixas Em ocasiões que você necessite travar certa tag para que não possa ser removida da interface, você pode defini-la como desabilitada. {{"demo": "pages/components/autocomplete/FixedTags.js"}} ### Caixas de seleção {{"demo": "pages/components/autocomplete/CheckboxesTags.js"}} ### Limitar tags Você pode usar a propriedade `limitTags` para limitrar o número de opções exibidas quando o componente não estiver com o foco. {{"demo": "pages/components/autocomplete/LimitTags.js"}} ## Tamanhos Gosta mais de campos de texto menores? Use a propriedade `size`. {{"demo": "pages/components/autocomplete/Sizes.js"}} ## Customizações ### Input customizado A propriedade `renderInput` permite que você customize o input renderizado. O primeiro argumento desta propriedade de render, contém propriedades que você precisa encaminhar. Preste atenção específicamente nas chaves `ref` e `inputProps`. {{"demo": "pages/components/autocomplete/CustomInputAutocomplete.js"}} ### Seletor do GitHub Esta demonstração reproduz o rótulo de seleção do GitHub's: {{"demo": "pages/components/autocomplete/GitHubLabel.js"}} Va para a seção [Hook customizado](#customized-hook) para um exemplo com o uso do hook customizado `useAutocomplete` ao invés do componente. ## Realce A demonstração a seguir dependem do [autosuggest-highlight](https://github.com/moroshko/autosuggest-highlight), um utilitário pequeno (1 kB) para realçar textos nos componentes autosuggest e autocomplete. {{"demo": "pages/components/autocomplete/Highlights.js"}} ## Filtro customizado O componente expõe uma fábrica para criar um método de filtro que pode ser fornecido para a propriedade `filterOptions`. Você pode usar ela para modificar o comportamento padrão do filtro. ```js import { createFilterOptions } from '@material-ui/lab/Autocomplete'; ``` ### `createFilterOptions(config) => filterOptions` #### Argumentos 1. `config` (*Object* [opcional]): - `config.ignoreAccents` (*Boolean* [opcional]): Padrão `true`. Remover sinais diacríticos. - `config.ignoreCase` (*Boolean* [opcional]): Padrão `true`. Minúsculas em tudo. - `config.limit` (*Number* [opcional]): Padrão null. Limitar o número de opções sugeridas a serem exibidas. Por exemplo, se `config.limit` é `100`, somente as primeiras `100` opções correspondentes são exibidas. Isto pode ser útil se um monte corresponderem e a virtualização não estiver configurada. - `config.matchFrom` (*'any' | 'start'* [opcional]): Padrão `'any'`. - `config.stringify` (*Func* [opcional]): Controla a forma como a opção é convertida em texto, dessa forma pode ser comparada com qualquer fragmento de texto. - `config.trim` (*Boolean* [opcional]): Padrão `false`. Remover espaços ao fim. #### Retornos `filterOptions`: o método de filtro retornado pode ser fornecido diretamente para a propriedade `filterOptions` do componente `Autocomplete` ou para o parâmetro de mesmo nome no hook. Na demonstração a seguir, as opções necessárias para o filtro ser aplicado no inicio das opções: ```js const filterOptions = createFilterOptions({ matchFrom: 'start', stringify: option => option.title, });