React Academy · Aula

Campos dinâmicos com useFieldArray

Adicione, remova e reordene campos dinâmicos de formulário usando o hook useFieldArray.

Campos dinâmicos com useFieldArray é uma aula grátis de React Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de React Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de React Academy inclui 4 aulas no total.

Boas-vindas

Nesta lição, você usará o hook useFieldArray do React Hook Form para criar formulários com listas dinâmicas de campos, como ao adicionar, remover e reordenar itens.

O que é useFieldArray?

useFieldArray gerencia uma matriz de campos dentro de um React Hook Form. Ele fornece os métodos append, prepend, remove, swap, move e insert para manipular a lista de campos.

import { useFieldArray } from 'react-hook-form';

const { fields, append, remove } = useFieldArray({
  control,
  name: 'phoneNumbers',
});

Configuração: control de useForm

useFieldArray exige o objeto `control` de useForm. Extraia-o junto com register e handleSubmit.

const { register, control, handleSubmit } = useForm({
  defaultValues: { phoneNumbers: [{ value: '' }] },
});

Renderizando os campos

Use map em `fields` para renderizar cada item. Use o `id` do campo como chave do React, não o índice. Registre cada campo usando a sintaxe de caminho da matriz.

return fields.map((field, index) => (
  <div key={field.id}>
    <input
      {...register(`phoneNumbers.${index}.value`)}
    />
    <button onClick={() => remove(index)}>Remove</button>
  </div>
));

Adicionando novos campos

Chame append() com um objeto de valor padrão para adicionar um novo campo ao final da lista. O formulário o registra automaticamente.

<button onClick={() => append({ value: '' })}>
  Add Phone Number
</button>

Removendo campos

Chame remove(index) para excluir um campo em uma posição específica. Todos os campos seguintes avançam uma posição, e seus registros são atualizados automaticamente.

<button onClick={() => remove(index)}>Delete</button>

Validação do número mínimo de campos

Você pode validar o tamanho da matriz em um schema do Zod com .min() para garantir que exista pelo menos um campo.

const schema = z.object({
  emails: z.array(z.object({ value: z.string().email() }))
           .min(1, 'At least one email required'),
});

Trocando e movendo campos

Use `swap(indexA, indexB)` para trocar dois campos ou `move(from, to)` para reposicionar um campo. Esses métodos são usados para criar listas de campos ordenáveis com arrastar e soltar.

swap(0, 2); // swap first and third items
move(3, 0); // move item at index 3 to the top

useFieldArray aninhado

Você pode aninhar useFieldArray dentro de outro useFieldArray para criar formulários dinâmicos com vários níveis, como uma fatura com itens de linha, cada um com subitens.

Enviando dados de uma matriz

No envio, handleSubmit passa a matriz completa como parte do objeto de dados. Acesse-a em data.phoneNumbers — uma matriz de objetos que corresponde à estrutura dos campos.

const onSubmit = (data) => {
  console.log(data.phoneNumbers);
  // [{ value: '555-1234' }, { value: '555-5678' }]
};

Verificação rápida

Por que você deve usar field.id, e não o índice da matriz, como chave do React ao renderizar campos de useFieldArray?

Recapitulação

useFieldArray fornece a matriz fields e os métodos append/remove/swap/move. Use field.id como chave do React, registre os campos com a sintaxe 'fieldName.index.subfield' e valide matrizes com min/max do Zod.

Curso concluído

Parabéns! Você concluiu **Gerenciamento de formulários com React Hook Form**. Agora você pode criar formulários eficientes com RHF, aplicar validação com schemas do Zod e criar matrizes dinâmicas de campos.

Perguntas Frequentes

A aula “Campos dinâmicos com useFieldArray” é grátis?

Sim — o texto completo de “Campos dinâmicos com useFieldArray” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de React Academy, atualize para CoddyKit PRO. O curso de React Academy inclui 4 aulas no total.

O que vou aprender em “Campos dinâmicos com useFieldArray”?

Adicione, remova e reordene campos dinâmicos de formulário usando o hook useFieldArray. Você pratica React Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar React Academy?

Nenhuma experiência prévia é necessária. React Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.

Quanto tempo leva a aula “Campos dinâmicos com useFieldArray”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de React Academy?

Sim. Cada aula de React Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para React Academy