Angular 22: como focar campos com o focusBoundControl
Aprenda a usar o focusBoundControl do Angular 22 para focar campos do Signal Forms sem ViewChild ou ElementRef, inclusive o primeiro inválido.
Quem já precisou focar um campo de formulário programaticamente no Angular conhece bem o roteiro: criar uma referência no template, buscar o elemento com @ViewChild (ou viewChild()), acessar o ElementRef e, finalmente, chamar o nativeElement.focus(). Funciona, mas é muito código para uma tarefa simples, além de nos obrigar a manipular o DOM diretamente.
Com o Signal Forms, que se tornou estável no Angular 22, temos uma forma bem mais elegante de resolver isso: o método focusBoundControl(). Ele foi introduzido na versão 21.1 (ainda em modo experimental) e agora faz parte da API estável do framework.
A ideia é simples: em vez de dizer ao navegador qual elemento deve receber o foco, nós pedimos ao formulário que foque o controle vinculado a um determinado campo. Afinal, o Signal Forms já conhece a estrutura do formulário, então por que percorrer o DOM manualmente?
Neste texto, vou mostrar, passo a passo, como utilizar o focusBoundControl() em alguns cenários comuns do dia a dia.
Vale mencionar que, se você ainda não conhece o Signal Forms, recomendo dar uma olhada no post anterior onde apresento os conceitos básicos dessa nova API:
Angular 21 - Formulários reativos com Signal Forms
Requisitos para replicar o exemplo
Para criar o cenário de estudo utilizei o Angular 22:
# Para conferir a versão do Node.js
# abra o terminal e digite:
node -v
# Para criar o projeto Angular 22
# utilizei o seguinte comando:
#
# Observação: optei em não instalar o CLI
# em modo global.
npx @angular/cli@22 new angular22
Com o projeto criado, basta executar o comando npm start e abrir o navegador no endereço localhost:4200.
Importante: a partir da versão 21.1 a diretiva [field], que utilizei no post anterior, passou a se chamar [formField] (classe FormField). Nos exemplos abaixo já utilizo o nome atual.
Passo 1 - Uso básico do focusBoundControl()
O focusBoundControl() é um método disponível no estado de cada campo do formulário, ou seja, no objeto retornado quando chamamos um campo como função (ex: formularioCliente.email()). Ao ser chamado, o Angular localiza o controle (input, textarea, select ou um controle customizado) vinculado àquele campo via [formField] e move o foco para ele.
Vamos partir de um formulário simples de cadastro de cliente:
import { Component, signal } from '@angular/core';
import {
email,
form,
FormField,
required,
} from '@angular/forms/signals';
interface Cliente {
nome: string;
email: string;
telefone: string;
}
@Component({
selector: 'app-root',
imports: [FormField],
templateUrl: './app.html'
})
export class App {
protected readonly cliente = signal<Cliente>({
nome: '',
email: '',
telefone: '',
});
protected readonly formularioCliente = form(
this.cliente,
(path) => {
required(path.nome, { message: 'Informe um nome' });
required(path.email, { message: 'Informe um email' });
email(path.email, { message: 'Informe um email válido' });
required(path.telefone, { message: 'Informe um telefone' });
}
);
focarEmail() {
// Basta chamar o focusBoundControl() no estado do campo
this.formularioCliente.email().focusBoundControl();
}
}app.ts
<h2>Cadastro de Cliente</h2>
<div>
<input
[formField]="formularioCliente.nome"
placeholder="nome..."
type="text" />
</div>
<div>
<input
[formField]="formularioCliente.email"
placeholder="email..."
type="email" />
</div>
<div>
<input
[formField]="formularioCliente.telefone"
placeholder="telefone..."
type="tel" />
</div>
<button type="button" (click)="focarEmail()">
Focar email
</button>app.html
Perceba que não foi necessário nenhum #referencia no template, nenhum viewChild() e nenhum ElementRef. O formulário já sabe qual input está vinculado ao campo email.
Passo 2 - Focando o primeiro campo inválido
Um cenário muito comum: o usuário clica em Salvar, o formulário está inválido e queremos levá-lo direto ao primeiro campo com erro. Isso melhora bastante a acessibilidade, principalmente para quem navega pelo teclado ou utiliza leitores de tela.
Para isso podemos combinar o focusBoundControl() com o errorSummary(), que retorna a lista de erros de todo o formulário. Cada erro possui a propriedade fieldTree, que aponta para o campo onde o erro ocorreu:
salvar() {
// Marca todos os campos como "tocados"
// para que as mensagens de erro apareçam
this.formularioCliente().markAsTouched();
const primeiroErro = this.formularioCliente()
.errorSummary()[0];
if (primeiroErro?.fieldTree) {
// Leva o usuário até o primeiro campo inválido
primeiroErro.fieldTree().focusBoundControl();
return;
}
console.log('Salvar', this.cliente());
}No template, adicionamos o <form> e as mensagens de erro:
<h2>Cadastro de Cliente</h2>
<form (submit)="salvar(); $event.preventDefault()" novalidate>
<div>
<input
[formField]="formularioCliente.nome"
placeholder="nome..."
type="text" />
</div>
@let campoNome = formularioCliente.nome();
@if (campoNome.touched() && campoNome.invalid()) {
<div style="color: red">
{{ campoNome.errors()[0].message }}
</div>
}
<div>
<input
[formField]="formularioCliente.email"
placeholder="email..."
type="email" />
</div>
@let campoEmail = formularioCliente.email();
@if (campoEmail.touched() && campoEmail.invalid()) {
<div style="color: red">
{{ campoEmail.errors()[0].message }}
</div>
}
<div>
<input
[formField]="formularioCliente.telefone"
placeholder="telefone..."
type="tel" />
</div>
@let campoTelefone = formularioCliente.telefone();
@if (campoTelefone.touched() && campoTelefone.invalid()) {
<div style="color: red">
{{ campoTelefone.errors()[0].message }}
</div>
}
<button type="submit">Salvar</button>
</form>Veja que, conforme o usuário corrige os campos e clica novamente em Salvar, o foco vai "pulando" para o próximo campo com erro, seguindo a ordem do formulário.
Exemplo
Passo 3 - Evitando a rolagem e trabalhando com controles customizados
Evitando a rolagem com preventScroll
Por padrão, quando o campo está fora da área visível da tela, o navegador faz a rolagem até ele ao receber o foco. Se você não quiser esse comportamento, basta passar a opção preventScroll:
this.formularioCliente.email().focusBoundControl({
preventScroll: true,
});Essa opção é a mesma do HTMLElement.focus() nativo do navegador.
Controles customizados
Agora um detalhe importante: se o campo estiver vinculado a um componente customizado, por padrão o focusBoundControl() não faz nada. O motivo é que um componente pode conter vários inputs (pense em um campo de data com dia, mês e ano separados) e o Angular não tem como saber qual deles deve receber o foco.
Para resolver isso, basta implementar um método focus() no componente. Quando o focusBoundControl() for chamado, o Angular vai executar esse método:
import {
Component,
ElementRef,
model,
viewChild,
} from '@angular/core';
import { FormValueControl } from '@angular/forms/signals';
@Component({
selector: 'app-input-telefone',
template: `
<input
#inputTelefone
type="tel"
placeholder="(11) 99999-9999"
[value]="value()"
(input)="value.set($any($event.target).value)" />
`,
})
export class InputTelefone implements FormValueControl<string> {
readonly value = model<string>('');
private readonly inputTelefone =
viewChild.required<ElementRef<HTMLInputElement>>(
'inputTelefone'
);
// Chamado automaticamente quando o focusBoundControl()
// é executado no campo vinculado a este componente
focus(): void {
this.inputTelefone().nativeElement.focus();
}
}input-telefone.ts
E no template do formulário, trocamos o input de telefone pelo nosso componente:
<app-input-telefone
[formField]="formularioCliente.telefone" />Perceba que o ElementRef não sumiu por completo, mas agora ele fica encapsulado dentro do componente, que é quem realmente sabe qual elemento deve receber o foco. Quem usa o componente continua apenas chamando o focusBoundControl().
Considerações
O focusBoundControl() é um recurso pequeno, mas que resolve um incômodo antigo de quem trabalha com formulários no Angular. Em vez de espalhar viewChild(), ElementRef e nativeElement.focus() pelos componentes, passamos a pedir ao próprio formulário que foque o campo desejado.
Combinado com o errorSummary(), ele também facilita bastante a implementação de boas práticas de acessibilidade, levando o usuário direto ao campo que precisa ser corrigido.
Vale lembrar que, com o Angular 22, o Signal Forms deixou de ser experimental e agora é estável, ou seja, já pode ser utilizado com tranquilidade em produção.
Links interessantes:
- https://angular.dev/guide/forms/signals/field-state-management
- https://angular.dev/guide/forms/signals/custom-controls
- https://blog.angular.dev/announcing-angular-v22-c52bb83a4664
Exemplo de uso: