MatFormFieldControl: entendendo o erro de uma vez por todas

Introdução: por que seu formulário Angular está gritando com um erro?

Você já se deparou com a seguinte situação: está escrevendo um formulário bonito no Angular Material, tudo parece perfeito, mas o console do navegador de repente exibe a mensagem:

mat-form-field must contain a MatFormFieldControl

Ou, se você estiver usando o modo estrito do TypeScript, pode aparecer algo como:

Error: mat-form-field must contain a MatFormFieldControl. Did you forget to add a directive that implements MatFormFieldControl?

Este é um dos erros mais populares no Stack Overflow (milhares de visualizações!), e hoje vamos analisá-lo de ponta a ponta. Você aprenderá não apenas como corrigir esse problema, mas também por que ele ocorre. E o principal: aprenderá a criar seus próprios controles para o Angular Material, se o padrão MatInput não atender às suas necessidades.

Vamos lá! 🚀

O que é MatFormFieldControl e para que serve?

Antes de tratar o erro, vamos entender a anatomia do Angular Material. mat-form-field é um contêiner que adiciona a estilização do Material Design (rótulo, sublinhado, dicas, erros). Mas por si só ele não exibe nada. Ele precisa de um "filho" — uma diretiva ou componente que implemente a interface MatFormFieldControl.

Essa interface (ou classe abstrata) descreve como o controle interage com o formulário: como obter o valor, como exibir o erro, como lidar com o foco. A implementação padrão é o MatInput. Se você escrever:

<mat-form-field>\n  <input matInput placeholder="Nome">\n</mat-form-field>

— a diretiva matInput implementa automaticamente o MatFormFieldControl.

O erro ocorre quando o Angular não encontra nenhum elemento filho com essa implementação. Por exemplo:

<mat-form-field>\n  <input placeholder="Nome"> <!-- Sem matInput! -->\n</mat-form-field>

Ou quando você tenta usar um componente personalizado que não implementou a interface.

Causas típicas do erro (e como corrigi-las)

1. Esqueceu de adicionar a diretiva matInput

A causa mais simples. Você simplesmente não colocou matInput no elemento <input>.

Incorreto:

<mat-form-field>\n  <input placeholder="Email">\n</mat-form-field>

Correto:

<mat-form-field>\n  <input matInput placeholder="Email">\n</mat-form-field>

Verifique também se você importou o MatInputModule no seu módulo:

import { MatInputModule } from '@angular/material/input';\n\n@NgModule({\n  imports: [MatInputModule]\n})\nexport class AppModule { }

2. Usando o elemento HTML errado

O MatInput funciona apenas com <input> e <textarea>. Se você tentar envolver um <div> comum ou <select> (sem mat-select) em um mat-form-field, receberá o erro.

Incorreto:

<mat-form-field>\n  <div>Algum conteúdo</div>\n</mat-form-field>

Correto: use os componentes Material apropriados:

<mat-form-field>\n  <mat-select placeholder="Cidade">\n    <mat-option value="1">São Paulo</mat-option>\n  </mat-select>\n</mat-form-field>

Para mat-select, é necessário importar o MatSelectModule.

3. Componente personalizado não implementa MatFormFieldControl

Este é um caso mais complexo. Suponha que você criou seu próprio componente para entrada de data ou classificação. O Angular Material não sabe sobre ele. É necessário "ensiná-lo" explicitamente.