FormControl e Input não estão funcionando? Resolvendo o problema do Angular Material

Introdução: A dor familiar de todo desenvolvedor Angular

Você já passou uma hora procurando um erro que estava escondido literalmente em uma única linha de código? Se você trabalha com Angular Material Autocomplete e se deparou com a mensagem Can't bind to 'formControl' since it isn't a known property of 'input' — você não está sozinho. Essa pergunta no Stack Overflow acumulou milhares de visualizações, e não é à toa. O erro aparece no momento mais inesperado, quando parece que tudo já está funcionando perfeitamente.

Neste artigo, vamos analisar as causas do erro, comparar detalhadamente três abordagens para corrigi-lo e mostrar exemplos funcionais em TypeScript. Após a leitura, você será capaz não apenas de consertar o autocomplete, mas também de entender mais profundamente a arquitetura do Angular. Vamos lá!

Por que o erro Can't bind to 'formControl' ocorre?

Vamos direto ao ponto. O erro aparece quando o Angular tenta vincular a diretiva formControl a um elemento <input>, mas não a encontra no módulo atual. Parece lógico, mas o diabo está nos detalhes.

Na verdade, formControl é o seletor de uma diretiva que faz parte do módulo ReactiveFormsModule. Se você esqueceu de importar este módulo ou o importou incorretamente, o Angular simplesmente não sabe o que fazer com o atributo [formControl] no seu input.

Aqui está uma situação típica: você cria um novo componente com autocomplete, adiciona FormControl no código TypeScript e, no template, escreve:

<input type="text" [formControl]="myControl" [matAutocomplete]="auto">\n<mat-autocomplete #auto="matAutocomplete">\n  <mat-option *ngFor="let option of filteredOptions | async" [value]="option">\n    {{option}}\n  </mat-option>\n</mat-autocomplete>

E então — bum! Erro vermelho no console. Familiar? Então continue lendo.

Abordagem 1: Importar ReactiveFormsModule (A mais simples e correta)

A primeira e mais óbvia maneira é garantir que o ReactiveFormsModule esteja importado no módulo correto. Para componentes standalone (Angular 14+) ou módulos clássicos, o procedimento é um pouco diferente.

Para módulos clássicos (NgModule)

Abra o arquivo do módulo onde seu componente está registrado (por exemplo, app.module.ts ou shared.module.ts) e adicione a importação:

import { ReactiveFormsModule } from '@angular/forms';\nimport { MatAutocompleteModule } from '@angular/material/autocomplete';\nimport { MatInputModule } from '@angular/material/input';\n\n@NgModule({\n  imports: [\n    ReactiveFormsModule,\n    MatAutocompleteModule,\n    MatInputModule,\n    // outras importações\n  ],\n  // ...\n})\nexport class AppModule { }

Importante: Sem o MatInputModule, a diretiva matInput também não funcionará, e você receberá um erro semelhante. Importe todos os três módulos juntos.

Para componentes standalone (Angular 14+ e Angular 17)

Se você estiver usando a nova arquitetura, a importação é feita diretamente no componente:

import { Component } from '@angular/core';\nimport { ReactiveFormsModule, FormControl } from '@angular/forms';\nimport { MatAutocompleteModule } from '@angular/material/autocomplete';\nimport { MatInputModule } from '@angular/material/input';\nimport { AsyncPipe } from '@angular/common';\n\n@Component({\n  selector: 'app-search',\n  standalone: true,\n  imports: [\n    ReactiveFormsModule,\n    MatAutocompleteModule,\n    MatInputModule,\n    AsyncPipe\n  ],\n  template: `\n    <input type="text" [formControl]="myControl" [matAutocomplete]="auto">\n    <mat-autocomplete #auto="matAutocomplete">\n      <mat-option *ngFor="let option of filteredOptions | async" [value]="option">\n        {{option}}\n      </mat-option>\n    </mat-