¿No coinciden FormControl e Input? Resolvemos el problema de Angular Material

Introducción: El dolor familiar de todo desarrollador Angular

¿Alguna vez has perdido una hora buscando un error que se escondía literalmente en una sola línea de código? Si trabajas con Angular Material Autocomplete y te has encontrado con el mensaje Can't bind to 'formControl' since it isn't a known property of 'input' — no estás solo. Esta pregunta en Stack Overflow ha acumulado miles de visitas, y con razón. El error aparece en el momento más inesperado, cuando parece que todo funciona perfectamente.

En este artículo, analizaremos las causas del error, compararemos detalladamente tres enfoques para solucionarlo y mostraremos ejemplos funcionales en TypeScript. Después de leerlo, no solo podrás reparar el autocompletado, sino también comprender más profundamente la arquitectura de Angular. ¡Vamos allá!

¿Por qué ocurre el error Can't bind to 'formControl'?

Vamos al grano. El error aparece cuando Angular intenta vincular la directiva formControl a un elemento <input>, pero no la encuentra en el módulo actual. Suena lógico, pero el diablo está en los detalles.

En realidad, formControl es el selector de una directiva que forma parte del módulo ReactiveFormsModule. Si olvidaste importar este módulo o lo importaste incorrectamente, Angular simplemente no sabe qué hacer con el atributo [formControl] en tu input.

Aquí tienes una situación típica: creas un nuevo componente con autocompletado, agregas FormControl en el código TypeScript, y en la plantilla escribes:

<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>

¡Y entonces, pum! Un error rojo en la consola. ¿Te suena? Entonces sigue leyendo.

Enfoque 1: Importar ReactiveFormsModule (El más simple y correcto)

La primera y más obvia forma es asegurarse de que ReactiveFormsModule esté importado en el módulo correcto. Para componentes independientes (Angular 14+) o módulos clásicos, el procedimiento es ligeramente diferente.

Para módulos clásicos (NgModule)

Abre el archivo del módulo donde está registrado tu componente (por ejemplo, app.module.ts o shared.module.ts) y agrega la importación:

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    // otras importaciones\n  ],\n  // ...\n})\nexport class AppModule { }

Importante: Sin MatInputModule, la directiva matInput tampoco funcionará y obtendrás un error similar. Importa los tres módulos juntos.

Para componentes independientes (Angular 14+ y Angular 17)

Si usas la nueva arquitectura, la importación se hace directamente en el 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-