Erro formGroup no Angular: como corrigir em 5 minutos

«Can't bind to 'formGroup' since it isn't a known property of 'form'» — uma dor familiar?

Se você já tentou criar um formulário no Angular e viu no console do navegador a mensagem vermelha Can't bind to 'formGroup' since it isn't a known property of 'form' — você não está sozinho. Esse erro está no top 5 das perguntas mais frequentes no Stack Overflow sobre Angular. Milhares de desenvolvedores (e eu inclusive) perderam horas tentando entender o que deu errado.

A boa notícia: a causa é quase sempre a mesma, e a correção leva 2 minutos. A má notícia: se você não souber onde olhar, pode reescrever o formulário inteiro e nunca encontrar a raiz do problema.

Neste artigo, vamos abordar:

\n
• Por que o erro formGroup unknown property ocorre
\n
• Como importar corretamente o ReactiveFormsModule
\n
• Três formas de corrigir o erro com exemplos de código em TypeScript
\n
• Como evitar o problema no futuro
\n

Vamos nessa! 🚀

O que significa o erro «Can't bind to 'formGroup'»?

Angular é um framework de tipagem estrita. Quando você escreve no template:

<form [formGroup]="myForm">

O Angular procura uma diretiva que saiba processar o atributo formGroup. Se essa diretiva não for encontrada, o framework exibe o erro: «Can't bind to 'formGroup' since it isn't a known property of 'form'».

É como tentar encaixar um cabo USB no lado errado. Parece que vai funcionar, mas os contatos não se alinham. O Angular simplesmente não sabe o que fazer com formGroup porque o módulo necessário não foi importado.

Causa principal: falta do ReactiveFormsModule

A diretiva formGroup vive no módulo ReactiveFormsModule. Se você não o importou no seu AppModule (ou no módulo onde o componente é usado), o Angular não consegue reconhecer o atributo.

Veja como é o cenário típico do erro:

\n
1. Você cria um componente com formulário
\n
2. No TypeScript, define um FormGroup
\n
3. No template, usa [formGroup]="myForm"
\n
4. Recebe o erro no console
\n

Como corrigir: exemplo completo de código em TypeScript

Vamos criar passo a passo um formulário funcional e analisar cada etapa.

Passo 1. Criar o componente com formulário

Primeiro, definimos o formulário no arquivo TypeScript do componente:

// my-form.component.ts\nimport { Component, OnInit } from '@angular/core';\nimport { FormGroup, FormControl, Validators } from '@angular/forms';\n\n@Component({\n  selector: 'app-my-form',\n  templateUrl: './my-form.component.html',\n  styleUrls: ['./my-form.component.css']\n})\nexport class MyFormComponent implements OnInit {\n  myForm!: FormGroup;\n\n  ngOnInit(): void {\n    this.myForm = new FormGroup({\n      name: new FormControl('', Validators.required),\n      email: new FormControl('', [Validators.required, Validators.email])\n    });\n  }\n\n  onSubmit(): void {\n    if (this.myForm.valid) {\n      console.log('Formulário enviado:', this.myForm.value);\n    }\n  }\n}

Passo 2. Template correto (HTML)

No template, usamos a diretiva formGroup:

<!-- my-form.component.html -->\n<form [formGroup]="myForm" (ngSubmit)="onSubmit()">\n  <div>\n    <label for="name">Nome:</label>\n    <input id="name" type="text" formControlName="name">\n  </div>\n\n  <div>\n    <label for="email">Email:</label>\n    <input id="email" type="email" formControlName="email">\n  </div>\n\n  <button type="submit" [disabled]="!myForm.valid">Enviar</button>\n</form>