Atributos de Evento Globais em HTML

Um evento ocorre quando o navegador reage a uma ação específica — um usuário clicando com o mouse, pressionando uma tecla, reproduzindo um vídeo, enviando um formulário, redimensionando a janela, entre outros. Para responder a um evento, você anexa um handler: um trecho de script (geralmente JavaScript) que é executado quando o evento é disparado.

O HTML permite anexar um handler diretamente na marcação através de um atributo de evento. Todos os atributos desta página começam com on seguido do nome do evento (onclick, onkeydown, onsubmit, …). Todos foram adicionados no HTML5 e aceitam código JavaScript como valor:

<button onclick="alert('Clicked!')">Click me</button>

Esses atributos de evento são globais — a maioria pode ser colocada em qualquer elemento — mas cada um só faz sentido no contexto correto (atributos de formulário em controles de formulário, atributos de mídia em <audio>/<video>, e assim por diante).

Aviso

Atributos on* inline são desaconselhados no código moderno. Eles misturam comportamento à sua marcação, não permitem anexar facilmente mais de um handler, e são bloqueados por uma Política de Segurança de Conteúdo restrita. Prefira addEventListener em um script separado, o que mantém HTML e JavaScript separados e permite que vários handlers escutem o mesmo evento:

<button id="myBtn">Click me</button>

<script>
  const btn = document.getElementById("myBtn");
  btn.addEventListener("click", () => {
    alert("Clicked!");
  });
</script>

As tabelas abaixo listam os atributos de evento por categoria. Para um tratamento mais completo de como os eventos funcionam no navegador, consulte Eventos JavaScript e os relacionados Atributos Globais HTML.

Atributos de Eventos de Janela

Os eventos de janela são disparados para o objeto window. Geralmente são colocados na tag <body>, onde o navegador os mapeia para window.

Atributo	Descrição
onafterprint	Disparado após o documento ter sido impresso.
onbeforeprint	Disparado antes de o documento ser impresso.
onbeforeunload	Disparado antes de o documento ser descarregado (por exemplo, quando o usuário está prestes a sair da página).
onblur	Disparado quando a janela perde o foco (o usuário muda para outra aba ou aplicativo).
onerror	Disparado quando ocorre um erro ao carregar o documento ou um recurso.
onhashchange	Disparado quando o fragmento (a parte da URL após `#`) muda.
onload	Disparado quando toda a página — imagens, CSS e scripts — terminou de carregar.
onmessage	Disparado quando a janela recebe uma mensagem (por exemplo, via `postMessage`).
onoffline	Disparado quando o navegador perde a conexão de rede.
ononline	Disparado quando o navegador recupera a conexão de rede.
onpagehide	Disparado quando o usuário navega para fora da página.
onpageshow	Disparado quando o usuário navega para a página.
onpopstate	Disparado quando a entrada ativa do histórico muda.
onresize	Disparado quando a janela é redimensionada.
onstorage	Disparado quando uma área de armazenamento web (`localStorage`/`sessionStorage`) é atualizada.
onunload	Disparado quando a página é descarregada (o documento está sendo removido).

<body onload="document.body.style.background = '#eef'">
  <p>This page changes its background colour once it has loaded.</p>
</body>

Atributos de Eventos de Formulário

Um evento que pode ocorrer dentro de um formulário é chamado de evento de formulário. Os eventos de formulário acontecem quando um usuário abre ou fecha um formulário, navega entre formulários ou trabalha com dados em um formulário.

Os atributos de eventos de formulário podem ser aplicados a todos os elementos HTML, mas geralmente são usados com controles de formulário como <input>, <select> e <textarea>.

Atributo	Descrição
onblur	Disparado quando um elemento perde o foco (o usuário usa Tab ou clica fora de um controle).
onchange	Disparado quando o valor de um controle muda e o controle perde o foco.
oncontextmenu	Disparado quando o menu de contexto (clique com o botão direito) é aberto no elemento.
onfocus	Disparado quando um elemento ganha foco.
oninput	Disparado imediatamente cada vez que o valor de um controle muda.
oninvalid	Disparado quando um controle enviado falha na validação de restrição.
onreset	Disparado quando um formulário é redefinido para seus valores iniciais.
onsearch	Disparado quando o usuário pesquisa em um campo `<input type="search">`.
onselect	Disparado quando o usuário seleciona texto dentro de um `<input>` ou `<textarea>`.
onsubmit	Disparado quando um formulário é enviado.

<form onsubmit="alert('Submitting…'); return false;">
  <input type="text" name="name"
         onfocus="this.style.background = '#ffd'"
         onblur="this.style.background = ''"
         placeholder="Your name">
  <button type="submit">Send</button>
</form>

Retornar false do onsubmit (ou chamar event.preventDefault() em JavaScript) impede que o formulário seja realmente enviado — útil durante os testes.

Atributos de Eventos de Teclado

Os atributos de eventos de teclado podem ser aplicados a todos os elementos HTML.

Atributo	Descrição
onkeydown	Disparado quando uma tecla é pressionada. Repete enquanto a tecla é mantida pressionada.
onkeypress	Disparado quando uma tecla de caractere é pressionada. Descontinuado — use `onkeydown` em vez disso.
onkeyup	Disparado quando uma tecla pressionada é solta.

<input type="text"
       onkeyup="document.getElementById('echo').textContent = this.value"
       placeholder="Type here">
<p>You typed: <span id="echo"></span></p>

Atributos de Eventos de Mouse

Os eventos de mouse ocorrem quando o mouse interage com o documento HTML. Os atributos podem ser aplicados a todos os elementos HTML.

Atributo	Descrição
onclick	Disparado quando o elemento é clicado.
ondblclick	Disparado quando o elemento recebe um duplo clique.
ondrag	Disparado repetidamente enquanto um elemento está sendo arrastado.
ondragend	Disparado quando uma operação de arrastar termina.
ondragenter	Disparado quando um elemento arrastado entra em um alvo de soltar válido.
ondragleave	Disparado quando um elemento arrastado sai de um alvo de soltar válido.
ondragover	Disparado repetidamente enquanto um elemento arrastado está sobre um alvo de soltar válido.
ondragstart	Disparado quando o usuário começa a arrastar um elemento.
ondrop	Disparado quando um elemento arrastado é solto em um alvo de soltar válido.
onmousedown	Disparado quando um botão do mouse é pressionado sobre o elemento.
onmousemove	Disparado sempre que o ponteiro se move enquanto está sobre o elemento.
onmouseout	Disparado quando o ponteiro sai do elemento.
onmouseover	Disparado quando o ponteiro move sobre o elemento.
onmouseup	Disparado quando um botão do mouse é liberado sobre o elemento.
onmousewheel	Obsoleto — use `onwheel` em vez disso.
onscroll	Disparado quando a barra de rolagem de um elemento é rolada.
onwheel	Disparado quando a roda do mouse gira para cima ou para baixo sobre o elemento.

<div onmousemove="this.textContent = event.offsetX + ', ' + event.offsetY"
     style="width:240px; height:120px; background:#eef; text-align:center; line-height:120px;">
  Move the mouse here
</div>

Atributos de Eventos de Área de Transferência

Atributo	Descrição
oncopy	Disparado quando o conteúdo de um elemento é copiado.
oncut	Disparado quando o conteúdo de um elemento é cortado.
onpaste	Disparado quando um conteúdo é colado em um elemento.

Atributos de Eventos de Mídia

Os eventos de mídia ocorrem em elementos de mídia, como vídeo, imagem e áudio. Os atributos podem ser aplicados a qualquer elemento HTML, mas geralmente são usados dentro de elementos audio, embed, img, object e video.

Atributo	Descrição
onabort	Disparado quando o carregamento da mídia é interrompido.
oncanplay	Disparado quando o navegador armazenou buffer suficiente para começar a reproduzir.
oncanplaythrough	Disparado quando o navegador estima que pode reproduzir até o final sem parar para armazenar em buffer.
oncuechange	Disparado quando a legenda ativa de uma faixa de texto (por exemplo, legendas ou closed captions) muda.
ondurationchange	Disparado quando a duração da mídia muda.
onemptied	Disparado quando a mídia fica vazia (por exemplo, a conexão é perdida).
onended	Disparado quando a reprodução chega ao final da mídia.
onerror	Disparado quando ocorre um erro ao carregar a mídia.
onloadeddata	Disparado quando o frame atual dos dados de mídia foi carregado.
onloadedmetadata	Disparado quando os metadados (duração, dimensões, …) foram carregados.
onloadstart	Disparado quando o navegador começa a carregar a mídia.
onpause	Disparado quando a reprodução é pausada.
onplay	Disparado quando a reprodução começa ou é retomada.
onplaying	Disparado quando a reprodução está realmente em execução (após o buffer, por exemplo).
onprogress	Disparado periodicamente enquanto o navegador carrega a mídia.
onratechange	Disparado quando a taxa de reprodução muda (por exemplo, avanço rápido).
onseeked	Disparado quando uma operação de busca termina.
onseeking	Disparado quando uma operação de busca começa.
onstalled	Disparado quando o navegador está tentando, mas não conseguindo, buscar dados de mídia.
onsuspend	Disparado quando o carregamento da mídia é intencionalmente pausado.
ontimeupdate	Disparado conforme a posição de reprodução muda durante a reprodução.
onvolumechange	Disparado quando o volume muda (incluindo silenciamento).
onwaiting	Disparado quando a reprodução para porque o próximo frame ainda não foi armazenado em buffer.

Outros Eventos

Atributo	Descrição
ontoggle	Disparado quando o usuário abre ou fecha um elemento `<details>`.

Informação

Alguns atributos que você pode encontrar em referências mais antigas — onredo, onundo e onshow — nunca fizeram parte do HTML padrão ou não são suportados pelos navegadores, por isso foram omitidos aqui.

Prática

O que são atributos de evento globais em HTML?

Atributos on*, disponíveis na maioria dos elementos HTML, que executam JavaScript quando um evento correspondente é disparado.Atributos que enviam dados ao servidor quando um evento ocorre.Handlers de evento que funcionam apenas em elementos de formulário.Um substituto para addEventListener que os navegadores não suportam mais.