CKTIS / JavaScript
HTMLElement.focus — definir o foco programaticamente
O método focus() move o foco para um elemento que o pode receber. Aprende em que difere o foco de um clique, como funcionam as opções de deslocamento e indicação do foco e como verificar o resultado.
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
element.focus();
element.focus({ preventScroll: true });
element.focus({ preventScroll: true, focusVisible: true });HTMLElement.focus define o foco num elemento, se este o puder receber; não executa um clique. Devolve undefined, e não um indicador de sucesso. Num documento simples, verifica o resultado com document.activeElement === element.
O elemento tem de poder receber o foco. tabindex="-1" permite focar programaticamente um elemento normal sem o adicionar à navegação sequencial com a tecla Tab. focus() não contorna as restrições aplicáveis a elementos desativados, a elementos tornados inativos por inert ou a elementos que não são apresentados devido a display: none.
Por predefinição, o método desloca a página para tornar o elemento visível; preventScroll: true impede esse deslocamento. Normalmente, o navegador decide se apresenta um indicador de foco. focusVisible: true solicita a sua apresentação. Não removas o indicador visível sem disponibilizares uma alternativa.
Esta é uma API do padrão HTML, não do ECMAScript. Os motores de navegador atuais suportam focus() na forma básica; verifica separadamente o suporte das opções nos navegadores de destino. Node 24 não comprova o suporte da API do navegador. O exemplo chama deliberadamente o método após uma ação do utilizador.
Exemplos
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Focus example</title>
<button id="move" type="button">Focus target</button>
<p id="target" tabindex="-1">Target</p>
<pre id="result"></pre>
<script>
const move = document.getElementById('move');
const target = document.getElementById('target');
const result = document.getElementById('result');
move.addEventListener('click', () => {
target.focus({ preventScroll: true });
result.textContent = String(document.activeElement === target);
});
</script>
</html>Resultado
true
O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.