Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

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.

Fontes