Pular para o conteúdo principal

Autocomplete

Base​

O Autocomplete é um componente para seleção de valores dentre uma lista de opções que podem ser filtradas com base em um termo digitado.

Modos de apresentação​

O Autocomplete se apresenta visualmente como um select (padrão) ou como um input, a mudança entre um destes dois modos pode ser feita através da propriedade kind.

Opções​

A lista de opções de um Autocomplete pode ser gerada de dois modos:

  • Por meio da propriedade options, através de um array de objetos
  • Por meio do subcomponente Autocomplete.Option

Através da propriedade options​

Utilize a propriedade options para definir a lista de opções de um componente Autocomplete. A propriedade options deve conter um array de objetos e, de modo geral, cada um desses objetos deve possuir os atributos label e value, representando respectivamente o texto e o valor da opção na lista.

Utilizando um array de opções sem os atributos label e value​

Utilize as propriedades getOptionLabel e getOptionValue quando os objetos do array não possuirem um atributo label ou value.

Através do subcomponente Autocomplete.Option​

Também é possível definir a lista de opções passando uma série de subcomponentes Autocomplete.Option como filhos do componente Autocomplete.

O subcomponente Autocomplete.Option possui uma série de propriedades que permitem customizar desde texto auxiliar, até ícone (consulte a documentação da API para mais detalhes). Contudo, estes elementos visuais não estão disponíveis para as opções geradas através da propriedade options, que só permite a customização do texto (label).

Informação
  • O Autocomplete leva em consideração apenas a propriedade label do Autocomplete.Option para filtrar as opções da listagem
  • As propriedades getOptionLabel e getOptionValue não tem efeito quando as opções são construídas através do subcomponente Autocomplete.Option

Seleção multipla​

Por padrão o usuário pode apenas selecionar uma opção entre as disponíveis na listagem do Autocomplete, contudo, através da propriedade multiple é possível habilitar a escolha de múltiplas opções.

Com o subcomponente Autocomplete.Option​

A propriedade multiple do Autocomplete também tem o mesmo efeito para uma listagem de opções geradas através do subcomponente Autocomplete.Option.

Desabilitando opções​

Adicione a propriedade disabled no subcomponente Autocomplete.Option para desabilitar uma opção específica.

Informação
  • Não é possível navegar ou selecionar opções desabilitadas
  • Você só consegue desabilitar opções através do subcomponente Autocomplete.Option, o mesmo não pode ser feito através da propriedade options do Autocomplete

Mostrando uma mensagem quando não houver opções​

Use a propriedade renderNoOption para adicionar uma mensagem quando não houver opções para serem exibidas.

Valor inicial e controle de estado​

Utilize a propriedade defaultValue para prover um valor inicial ao componente Autocomplete não controlado, ou utilize a propriedade value para gerenciar o valor do Autocomplete controlado.

A opção selecionada (ou opções selecionadas, no caso de um Autocomplete com seleção múltipla) será definida através da igualdade estrita entre os atributos label e value das opções e do valor passado para a propriedade defaultValue ou value.

Informação

Tanto a propriedade defaultValue quanto value estão sujeitos aos efeitos das propriedades getOptionLabel e getOptionvalue.

Não controlado​

É possível utilizar o parâmetro defaultValue para definir o valor inicial do Autocomplete.

Controlado​

Você deve criar um estado para gerenciar o valor através da propriedade value ao utilizar o Autocomplete controlado.

Requisições assíncronas​

É possível carregar assíncronamente as opções do Autocomplete de dois modos distintos:

  • Ao abrir o Autocomplete
  • Com base no texto digitado enquanto se filtra

Em ambos os modos é importante assinalar visualmente que o componente está carregando as opções através da propriedade loading.

Carregando as opções ao abrir o Autocomplete​

Utilize o evento onOpen para buscar os dados necessários para montar dinamicamente a lista de opções.

Atenção!

Por questões de performance e usabilidade, não é ideal buscar os dados para montar a lista de opções toda vez que o usuário abrir o Autocomplete. Pense em políticas de cache e retentativas adequadas para o seu cenário.

Carregando as opções ao filtrar​

Utilize o evento onInputChange para buscar os dados necessários para montar dinamicamente a lista de opções enquanto o usuário digita no filtro do Autocomplete.

Atenção!

Por questões de performance e usabilidade, não é ideal buscar os dados para montar a lista de opções toda vez que um novo caractere é digitado no filtro do Autocomplete. Pense em estratégias de otimização como throttle e debounce adequadas ao seu cenário.

Separadores​

Utilize os subcomponentes Autocomplete.Title e Autocomplete.Divider para agrupar ou separar opções.

Informação

O uso de separadores não está disponível para geração de opções através da propriedade options do Autocomplete.

Agrupador com texto​

Utilize o subcomponente Autocomplete.Title para agrupar opções.

Informação

O filtro do Autocomplete não leva em consideração o texto do subcomponente Autocomplete.Title.

Divisor com linha​

Utilize o subcomponente Autocomplete.Divider para separar opções.

Utilize a propriedade renderFooter para renderizar um rodapé após a lista de opções. Esta propriedade aceita um componente com as seguintes propriedades:

  • inputValue: O valor atual do input
  • hasOption: Indica se há opções sendo exibidas
  • close: Função para fechar o Autocomplete
  • selectedOption: Opção selecionada, presente quando o Autocomplete for de seleção única
  • selectedOptions: Lista com as opções selecionadas, presente quando o Autocomplete for de múltipla seleção
  • clearInputValue: Função para limpar o valor do input

Desabilitado​

Utilize a propriedade disabled do Autocomplete para desabilitar o componente como um todo.

Com o componente Tag​

Com texto de apoio​

Padrão​

Utilize o subcomponente Form.Feedback para incluir textos de apoio ao Autocomplete.

Informação

Utilize o atributo aria-describedby para vincular o componente Autocomplete ao texto de apoio.

Sucesso​

A mensagem de sucesso, assim como seu estilo, deve ser aplicada somente quando o campo precisar de alguma validação. Os estados de sucesso e erro não têm relação direta entre si.

Erro​

Se o Autocomplete for preenchido incorretamente, ou seus critérios não forem atendidos, deve ser exibida uma mensagem de erro como validação.

Atenção!

Após correção do erro, o estado do campo deve voltar para o estilo padrão.

Integração com o Form.Control​

Assim como em outros componentes de formulário, o componente Autocomplete está integrado com o subcomponente Form.Control e recebe as propriedades error e success automaticamente por meio dessa integração.

React Hook Form​

Use o componente Autocomplete junto com o React Hook Form. Para isso, instale essa dependência no projeto:

yarn add react-hook-form
import React, { useState } from 'react';
import { useForm, Controller } from 'react-hook-form';
import {
  Form,
  Autocomplete,
  Text,
  Button
} from '@resultadosdigitais/tangram-components';

export default function WithReactHookForm() {
  const [submitted, onSubmit] = useState(false);

  const currencies = [
    { value: 'BRL', label: 'Real' },
    { value: 'USD', label: 'Dolar' },
    { value: 'EUR', label: 'Euro' }
  ];

  const {
    control,
    setValue,
    handleSubmit,
    formState: { errors }
  } = useForm();

  const CURRENCY = 'currency';

  const handleFieldChange = field => (_, option) => {
    field.onChange(option);
  };

  const handleClear = () => {
    setValue(CURRENCY, null);
  };

  return (
    <>
      {submitted && (
        <Text>
          <strong>Submitted: </strong>
          <code>{JSON.stringify(submitted)}</code>
        </Text>
      )}

      <Form onSubmit={handleSubmit(onSubmit)}>
        <Form.Label htmlFor={CURRENCY}>Currency</Form.Label>
        <Form.Control error={Boolean(errors.currency)}>
          <Controller
            control={control}
            name={CURRENCY}
            defaultValue={null}
            render={({ field }) => (
              <Autocomplete
                id={CURRENCY}
                name={CURRENCY}
                options={currencies}
                placeholder="Select currency"
                renderNoOption="No currency found"
                aria-describedby={`${CURRENCY}-feedback`}
                onChange={handleFieldChange(field)}
                onClear={handleClear}
              />
            )}
            rules={{ required: true }}
          />

          {errors.currency && (
            <Form.Feedback id={`${CURRENCY}-feedback`}>
              This field is required
            </Form.Feedback>
          )}
        </Form.Control>

        <Button type="submit">Submit</Button>
      </Form>
    </>
  );
}

Veja e teste o exemplo completo abaixo:

Feedback​