Pular para o conteúdo principal

Phone

Base​

País inicialmente selecionado​

Baseado no número do telefone​

Atenção!

O valor inicial das propriedades value ou defaultValue deve, obrigatoriamente, começar com o caractere +, seguido pelo código do país.

O país inicialmente selecionado será identificado, principalmente, pelo número de telefone passado para as propriedades value ou defaultValue, durante a inicialização do componente.

A ausência de uma dessas informações pode impedir o componente de identificar automaticamente o país, provocando a exibição de um alerta, como no exemplo abaixo:

Baseado no valor da propriedade defaultCountry​

Também é possível indicar o país selecionado através da propriedade defaultCountry, inserindo o código do país no formato ISO de dois dígitos.

Baseado no idioma padrão do navegador​

Caso nenhum valor seja passado para as propriedades value, defaultValue ou defaultCountry, o país selecionado será identificado automaticamente com base no idioma padrão do navegador da pessoa usuária.

Máscaras adaptáveis​

Durante a digitação do número do telefone, o componente Phone automaticamente ajusta a máscara para o formato adequado - quando o país selecionado tiver mais de um formato aplicável.

Como é o caso do Brasil, que possui que possui um formato para telefones fixos ((99) 9999-9999) e outro para números de celular ((99) 99999-9999).

Não controlado vs. Controlado​

Diferente de outros componentes de formulário, o Phone não suporta uma versão controlada.

Habilitar este tipo de controle conflitaria com a existência de máscaras para os formatos de telefone de diferentes países.

Por esta razão, a propriedade value é apenas um alias para a propriedade defaultValue e existe para manter a consistência com os demais componentes de formulário.

Veja no exemplo abaixo como o componente Phone pode ser usado simulando um comportamento controlado em um cenário real.

Eventos de formulário​

Todos os eventos-chave de interação com o componente (onChange, onClear, onBlur e onFocus) esperam callbacks que suportem os mesmos tipos de parâmetros, em ordem:

  1. O objeto para o evento disparado
  2. O valor do campo sem a máscara e com o código do país
  3. Informações gerais sobre o estado do componente, como país selecionado, validade do valor inserido, entre outros
Atenção

Não use a propriedade target.value, proveniente do objeto do evento, para alterar o estado do formulário. Este argumento recebe o valor do campo como presente no input, ou seja, com máscara e sem o código do país.

O segundo argumento é mais adequado para alterar o estado do formulário, já que seu valor corresponde ao número de telefone digitado, sem máscara e com o código do país. Portanto, está no formato adequado para servir de entrada as propriedades value e defaultValue e para ser armazenado em bancos de dados.

Para mais detalhes acesse nossa aba de API do componente.

Erros e validações​

A propriedade error permite exibir o componente com aparência de inválido.

Integração com Form.Control​

Assim como em outros componentes de formulário, o componente Phone está integrado com o componente Form.Control e recebe a propriedade error automaticamente por meio dessa integração.

Validando o número de telefone​

A validação do número digitado pode ser conferida em cada um dos eventos citados anteriormente, através do atributo valid, presente no objeto com informações adicionais. Esta informação pode ser usada para validar o número do telefone digitado pela pessoa usuária.

React Hook Form​

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

yarn add react-hook-form

Veja e teste o exemplo completo abaixo:

function ExampleWithReactHookForm() {
  const { control, watch } = useForm();
  const name = 'phone';

  return (
    <Form.Control>
      <Controller
        control={control}
        name={name}
        defaultValue={null}
        render={({ onChange }) => (
          <Phone
            id={name}
            name={name}
            onClear={() => onChange('')}
            onChange={(_, phone) => onChange(phone)}
          />
        )}
      />

      <Form.Feedback>{watch(name)}</Form.Feedback>
    </Form.Control>
  );
}

Internacionalização​

É possível passar valores customizados para os diferentes textos usados internamente pelo componente. São eles:

  • countryNames: Nomes customizados para os países
  • countryCallingCodeLabelText: Texto customizado para rotular o código do país. Este texto não é exibido, mas é útil para acessibilidade
  • selectedCountryLabelText: Texto customizado para rotular a seleção do país. Este texto não é exibido, mas é útil para acessibilidade
  • clearLabelText: Texto customizado para rotular o botão de limpar. Este texto não é exibido, mas é útil para acessibilidade
  • unidentifiedCountryTooltip: Texto customizado para o Tooltip, exibido quando o país não foi adequadamente identificado (veja a seção País inicialmente selecionado)
Atenção

Ao mudar o idioma padrão do componente (inglês), deve ser definidos novos valores para todas as propriedades citadas acima.

Para ajudar neste processo, constantes estão disponíveis com valores padrão para estas propriedades em inglês, português e espanhol. Para mais detalhes acesse nossa aba de API do componente.

Abaixo um exemplo de uso destas constantes para o Português:

Feedback​