API de Referência
Components

Componentes comuns (por exemplo, <div>)

Todos os componentes nativos do navegador, como <div>, suportam algumas props e eventos comuns.

Referência

Componentes comuns (por exemplo, <div>) 

<div className="wrapper">Algum conteúdo</div>

Veja mais exemplos abaixo.

Props

Estas props especiais do React são suportadas para todos os componentes nativos:

  • children: Um nó React (um elemento, uma string, um número, um portal, um nó vazio como null, undefined e booleanos, ou um array de outros nós React). Especifica o conteúdo dentro do componente. Quando você usa JSX, você geralmente especificará a prop children implicitamente ao aninhar tags como <div><span /></div>.

  • dangerouslySetInnerHTML: Um objeto do formulário { __html: '<p>some html</p>' } com uma string HTML bruta dentro. Substitui a propriedade innerHTML do nó DOM e exibe o HTML passado dentro. Isso deve ser usado com extrema cautela! Se o HTML dentro não for confiável (por exemplo, se for baseado em dados do usuário), você corre o risco de introduzir uma vulnerabilidade XSS. Leia mais sobre o uso de dangerouslySetInnerHTML.

  • ref: Um objeto ref de useRef ou createRef, ou uma ref função callback, ou uma string para refs legados. Seu ref será preenchido com o elemento DOM para este nó. Leia mais sobre como manipular o DOM com refs.

  • suppressContentEditableWarning: Um booleano. Se true, suprime o aviso que o React mostra para elementos que têm children e contentEditable={true} (que normalmente não funcionam juntos). Use isso se você estiver construindo uma biblioteca de entrada de texto que gerencia o conteúdo contentEditable manualmente.

  • suppressHydrationWarning: Um booleano. Se você usar renderização no servidor, normalmente há um aviso quando o servidor e o cliente renderizam conteúdo diferente. Em alguns casos raros (como timestamps), é muito difícil ou impossível garantir uma correspondência exata. Se você definir suppressHydrationWarning como true, o React não o avisará sobre incompatibilidades nos atributos e no conteúdo desse elemento. Ele só funciona em um nível de profundidade e é projetado para ser usado como uma porta de saída. Não use em excesso. Leia sobre como suprimir erros de hidratação.

  • style: Um objeto com estilos CSS, por exemplo, { fontWeight: 'bold', margin: 20 }. Semelhante à propriedade style, os nomes das propriedades CSS precisam ser escritos como camelCase, por exemplo, fontWeight em vez de font-weight. Você pode passar strings ou números como valores. Se você passar um número, como width: 100, o React anexará automaticamente px (“pixels”) ao valor, a menos que seja uma propriedade sem unidade. Recomendamos que você use style apenas para estilos dinâmicos nos quais você não conhece os valores do estilo com antecedência. Em outros casos, aplicar classes CSS simples com className é mais eficiente. Leia mais sobre className e style.

Essas props DOM padrão também são suportadas para todos os componentes nativos:* accessKey: Uma string. Especifica um atalho de teclado para o elemento. Geralmente não recomendado.

  • aria-*: Atributos ARIA permitem que você especifique as informações da árvore de acessibilidade para este elemento. Veja Atributos ARIA para uma referência completa. Em React, todos os nomes de atributos ARIA são exatamente os mesmos no HTML.
  • autoCapitalize: Uma string. Especifica se e como a entrada do usuário deve ser capitalizada.
  • className: Uma string. Especifica o nome da classe CSS do elemento. Leia mais sobre como aplicar estilos CSS.
  • contentEditable: Um booleano. Se true, o navegador permite que o usuário edite o elemento renderizado diretamente. Ele é usado para implementar bibliotecas de entrada de texto avançadas como Lexical. React avisa se você tentar passar os filhos React para um elemento com contentEditable={true} porque o React não poderá atualizar o conteúdo depois das edições do usuário.
  • data-*: Atributos de dados permitem que você anexe alguns dados de string ao elemento, por exemplo, data-fruit="banana". Em React, eles não são comumente usados porque você geralmente leria dados de props ou state em vez disso.
  • dir: 'ltr' ou 'rtl'. Especifica a direção do texto do elemento.
  • draggable: Um booleano. Especifica se o elemento é arrastável. Parte da API HTML Drag and Drop.
  • enterKeyHint: Uma string. Especifica qual ação apresentar para a tecla Enter em teclados virtuais.
  • htmlFor: Uma string. Para <label> e <output>, permite que você associe o rótulo com algum controle. Mesma coisa que o atributo HTML for. React usa os nomes de propriedade DOM padrão (htmlFor) em vez de nomes de atributo HTML.
  • hidden: Um booleano ou uma string. Especifica se o elemento deve ser ocultado.
  • id: Uma string. Especifica um identificador exclusivo para este elemento, que pode ser usado para encontrá-lo mais tarde ou conectá-lo com outros elementos. Gere-o com useId para evitar conflitos entre várias instâncias do mesmo componente.
  • is: Uma string. Se especificado, o componente se comportará como um elemento personalizado.
  • inputMode: Uma string. Especifica que tipo de teclado exibir (por exemplo, texto, número ou telefone).
  • itemProp: Uma string. Especifica qual propriedade o elemento representa para rastreadores de dados estruturados.
  • lang: Uma string. Especifica o idioma do elemento.
  • onAnimationEnd: Uma função de AnimationEvent handler. Dispara quando uma animação CSS é concluída.
  • onAnimationEndCapture: Uma versão de onAnimationEnd que dispara na fase de captura.
  • onAnimationIteration: Uma função de AnimationEvent handler. Dispara quando uma iteração de uma animação CSS termina, e outra começa.
  • onAnimationIterationCapture: Uma versão de onAnimationIteration que dispara na fase de captura.
  • onAnimationStart: Uma função de AnimationEvent handler. Dispara quando uma animação CSS começa.
  • onAnimationStartCapture: onAnimationStart, mas dispara na fase de captura.
  • onAuxClick: Uma função de MouseEvent handler. Dispara quando um botão de ponteiro não primário foi clicado.
  • onAuxClickCapture: Uma versão de onAuxClick que dispara na fase de captura.
  • onBeforeInput: Uma função de InputEvent handler. Dispara antes que o valor de um elemento editável seja modificado. React não usa ainda o evento nativo beforeinput, e em vez disso tenta polyfill usando outros eventos.
  • onBeforeInputCapture: Uma versão de onBeforeInput que dispara na fase de captura.
  • onBlur: Uma função de FocusEvent handler. Dispara quando um elemento perde o foco. Diferente do evento blur embutido no navegador, em React o evento onBlur propaga.
  • onBlurCapture: Uma versão de onBlur que dispara na fase de captura.
  • onClick: Uma função de MouseEvent handler. Dispara quando o botão primário foi clicado no dispositivo apontador.
  • onClickCapture: Uma versão de onClick que dispara na fase de captura.
  • onCompositionStart: Uma função de CompositionEvent handler. Dispara quando um input method editor inicia uma nova sessão de composição.
  • onCompositionStartCapture: Uma versão de onCompositionStart que dispara na fase de captura.
  • onCompositionEnd: Uma função de CompositionEvent handler. Dispara quando um input method editor conclui ou cancela uma sessão de composição.
  • onCompositionEndCapture: Uma versão de onCompositionEnd que dispara na fase de captura.
  • onCompositionUpdate: Uma função de CompositionEvent handler. Dispara quando um input method editor recebe um novo caractere.
  • onCompositionUpdateCapture: Uma versão de onCompositionUpdate que dispara na fase de captura.
  • onContextMenu: Uma função de MouseEvent handler. Dispara quando o usuário tenta abrir um menu de contexto.
  • onContextMenuCapture: Uma versão de onContextMenu que dispara na fase de captura.
  • onCopy: Uma função de ClipboardEvent handler. Dispara quando o usuário tenta copiar algo na área de transferência.
  • onCopyCapture: Uma versão de onCopy que dispara na fase de captura.
  • onCut: Uma função de ClipboardEvent handler. Dispara quando o usuário tenta cortar algo na área de transferência.
  • onCutCapture: Uma versão de onCut que dispara na fase de captura.
  • onDoubleClick: Uma função de MouseEvent handler. Dispara quando o usuário clica duas vezes. Corresponde ao evento dblclick do navegador.
  • onDoubleClickCapture: Uma versão de onDoubleClick que dispara na fase de captura.
  • onDrag: Uma função de DragEvent handler. Dispara enquanto o usuário está arrastando algo.
  • onDragCapture: Uma versão de onDrag que dispara na fase de captura.
  • onDragEnd: Uma função de DragEvent handler. Dispara quando o usuário para de arrastar algo.
  • onDragEndCapture: Uma versão de onDragEnd que dispara na fase de captura.
  • onDragEnter: Uma função de DragEvent handler. Dispara quando o conteúdo arrastado entra em um destino válido.
  • onDragEnterCapture: Uma versão de onDragEnter que dispara na fase de captura.
  • onDragOver: Uma função de DragEvent handler. Dispara em um destino válido enquanto o conteúdo arrastado é arrastado sobre ele. Você deve chamar e.preventDefault() aqui para permitir soltar.
  • onDragOverCapture: Uma versão de onDragOver que dispara na fase de captura.
  • onDragStart: Uma função de DragEvent handler. Dispara quando o usuário começa a arrastar um elemento.
  • onDragStartCapture: Uma versão de onDragStart que dispara na fase de captura.
  • onDrop: Uma função de DragEvent handler. Dispara quando algo é solto em um destino válido.
  • onDropCapture: Uma versão de onDrop que dispara na fase de captura.
  • onFocus: Uma função de FocusEvent handler. Dispara quando um elemento recebe foco. Diferente do evento focus embutido no navegador, em React o evento onFocus propaga.
  • onFocusCapture: Uma versão de onFocus que dispara na fase de captura.
  • onGotPointerCapture: Uma função de PointerEvent handler. Dispara quando um elemento captura programaticamente um ponteiro.
  • onGotPointerCaptureCapture: Uma versão de onGotPointerCapture que dispara na fase de captura.
  • onKeyDown: Uma função de KeyboardEvent handler. Dispara quando uma tecla é pressionada.
  • onKeyDownCapture: Uma versão de onKeyDown que dispara na fase de captura.
  • onKeyPress: Uma função de KeyboardEvent handler. Obsoleto. Use onKeyDown ou onBeforeInput em vez disso.
  • onKeyPressCapture: Uma versão de onKeyPress que dispara na fase de captura.
  • onKeyUp: Uma função de KeyboardEvent handler. Dispara quando uma tecla é solta.
  • onKeyUpCapture: Uma versão de onKeyUp que dispara na fase de captura.
  • onLostPointerCapture: Uma função de PointerEvent handler. Dispara quando um elemento para de capturar um ponteiro.
  • onLostPointerCaptureCapture: Uma versão de onLostPointerCapture que dispara na fase de captura.
  • onMouseDown: Uma função de MouseEvent handler. Dispara quando o ponteiro é pressionado.
  • onMouseDownCapture: Uma versão de onMouseDown que dispara na fase de captura.
  • onMouseEnter: Uma função de MouseEvent handler. Dispara quando o ponteiro se move para dentro de um elemento. Não possui uma fase de captura. Em vez disso, onMouseLeave e onMouseEnter propagam do elemento que está saindo para aquele que está entrando.
  • onMouseLeave: Uma função de MouseEvent handler. Dispara quando o ponteiro se move para fora de um elemento. Não possui uma fase de captura. Em vez disso, onMouseLeave e onMouseEnter propagam do elemento que está saindo para aquele que está entrando.
  • onMouseMove: Uma função de MouseEvent handler. Dispara quando o ponteiro muda de coordenadas.
  • onMouseMoveCapture: Uma versão de onMouseMove que dispara na fase de captura.
  • onMouseOut: Uma função de MouseEvent handler. Dispara quando o ponteiro se move para fora de um elemento, ou se ele se move para um elemento filho.
  • onMouseOutCapture: Uma versão de onMouseOut que dispara na fase de captura.
  • onMouseUp: Uma função de MouseEvent handler. Dispara quando o ponteiro é solto.
  • onMouseUpCapture: Uma versão de onMouseUp que dispara na fase de captura.
  • onPointerCancel: Uma função de PointerEvent handler. Dispara quando o navegador cancela uma interação de ponteiro.
  • onPointerCancelCapture: Uma versão de onPointerCancel que dispara na fase de captura.
  • onPointerDown: Uma função de PointerEvent handler. Dispara quando um ponteiro se torna ativo.
  • onPointerDownCapture: Uma versão de onPointerDown que dispara na fase de captura.
  • onPointerEnter: Uma função de PointerEvent handler. Dispara quando um ponteiro se move para dentro de um elemento. Não possui uma fase de captura. Em vez disso, onPointerLeave e onPointerEnter propagam do elemento que está saindo para aquele que está entrando.
  • onPointerLeave: Uma função de PointerEvent handler. Dispara quando um ponteiro se move para fora de um elemento. Não possui uma fase de captura. Em vez disso, onPointerLeave e onPointerEnter propagam do elemento que está saindo para aquele que está entrando.
  • onPointerMove: Uma função de PointerEvent handler. Dispara quando um ponteiro muda de coordenadas.
  • onPointerMoveCapture: Uma versão de onPointerMove que dispara na fase de captura.
  • onPointerOut: Uma função de PointerEvent handler. Dispara quando um ponteiro se move para fora de um elemento, se a interação do ponteiro for cancelada e alguns outros motivos.
  • onPointerOutCapture: Uma versão de onPointerOut que dispara na fase de captura.
  • onPointerUp: Uma função de PointerEvent handler. Dispara quando um ponteiro não está mais ativo.
  • onPointerUpCapture: Uma versão de onPointerUp que dispara na fase de captura.
  • onPaste: Uma função de ClipboardEvent handler. Dispara quando o usuário tenta colar algo da área de transferência.
  • onPasteCapture: Uma versão de onPaste que dispara na fase de captura.
  • onScroll: Uma função de Event handler. Dispara quando um elemento foi rolado. Este evento não propaga.
  • onScrollCapture: Uma versão de onScroll que dispara na fase de captura.
  • onSelect: Uma função de Event handler. Dispara após a seleção dentro de um elemento editável, como uma alteração de entrada. React estende o evento onSelect para funcionar também para elementos com contentEditable={true}. Além disso, React o estende para disparar para seleção vazia e em edições (o que pode afetar a seleção).
  • onSelectCapture: Uma versão de onSelect que dispara na fase de captura.
  • onTouchCancel: Uma função de TouchEvent handler. Dispara quando o navegador cancela uma interação touch.
  • onTouchCancelCapture: Uma versão de onTouchCancel que dispara na fase de captura.
  • onTouchEnd: Uma função de TouchEvent handler. Dispara quando um ou mais pontos de toque são removidos.
  • onTouchEndCapture: Uma versão de onTouchEnd que dispara na fase de captura.
  • onTouchMove: Uma função de TouchEvent handler. Dispara quando um ou mais pontos de toque são movidos.
  • onTouchMoveCapture: Uma versão de onTouchMove que dispara na fase de captura.
  • onTouchStart: Uma função de TouchEvent handler. Dispara quando um ou mais pontos de toque são colocados.
  • onTouchStartCapture: Uma versão de onTouchStart que dispara na fase de captura.
  • onTransitionEnd: Uma função de TransitionEvent handler. Dispara quando uma transição CSS é concluída.
  • onTransitionEndCapture: Uma versão de onTransitionEnd que dispara na fase de captura.
  • onWheel: Uma função de WheelEvent handler. Dispara quando o usuário gira um botão da roda.
  • onWheelCapture: Uma versão de onWheel que dispara na fase de captura.
  • role: Uma string. Especifica a função do elemento explicitamente para tecnologias assistivas.
  • slot: Uma string. Especifica o nome do slot ao usar shadow DOM. Em React, um padrão equivalente é normalmente alcançado passando JSX como props, por exemplo, <Layout left={<Sidebar />} right={<Content />} />.
  • spellCheck: Um booleano ou nulo. Se definido explicitamente como true ou false, habilita ou desabilita a verificação ortográfica.
  • tabIndex: Um número. Substitui o comportamento padrão do botão Tab. Evite usar valores diferentes de -1 e 0.
  • title: Uma string. Especifica o texto da dica de ferramenta para o elemento.
  • translate: 'yes' ou 'no'. Passar 'no' exclui o conteúdo do elemento de ser traduzido. Você também pode passar atributos customizados como props, por exemplo mycustomprop = "someValue". Isso pode ser útil ao integrar com bibliotecas de terceiros. O nome do atributo customizado deve estar em caixa baixa e não deve começar com on. O valor será convertido em uma string. Se você passar null ou undefined, o atributo customizado será removido.

Esses eventos disparam apenas para os elementos <form>:

Esses eventos disparam apenas para os elementos <dialog>. Diferente dos eventos do navegador, eles propagam no React:

Esses eventos disparam apenas para os elementos <details>. Diferente dos eventos do navegador, eles propagam no React:

Esses eventos disparam para elementos <img>, <iframe>, <object>, <embed>, <link> e SVG <image>. Diferente dos eventos do navegador, eles propagam no React:

Esses eventos disparam para recursos como <audio> e <video>. Diferente dos eventos do navegador, eles propagam no React:

Ressalvas

  • Você não pode passar children e dangerouslySetInnerHTML ao mesmo tempo.
  • Alguns eventos (como onAbort e onLoad) não propagam no navegador, mas propagam no React.

Função de callback ref ```

Em vez de um objeto ref (como o que é retornado por useRef), você pode passar uma função para o atributo ref.

<div ref={(node) => {
  console.log('Attached', node);

  return () => {
    console.log('Clean up', node)
  }
}}>

Veja um exemplo de como usar o callback ref.

Quando o nó DOM <div> é adicionado à tela, React chamará seu callback ref com o node DOM como argumento. Quando esse nó DOM <div> for removido, React chamará sua função de limpeza retornada do callback.

React também chamará seu callback ref sempre que você passar um callback ref diferente. No exemplo acima, (node) => { ... } é uma função diferente a cada renderização. Quando seu componente renderizar novamente, a função anterior será chamada com null como argumento, e a função seguinte será chamada com o nó DOM.

Parâmetros

  • node: Um nó DOM. React passará o nó DOM quando a ref for anexada. A menos que você passe a mesma referência de função para o callback ref em cada renderização, o callback será temporariamente limpo e recriado durante cada nova renderização do componente.

Note

O React 19 adicionou funções de limpeza para callbacks ref.

Para dar suporte à compatibilidade com versões anteriores, se uma função de limpeza não for retornada do callback ref, node será chamada com null quando a ref for desanexada. Esse comportamento será removido em uma versão futura.

Retorna

  • opcional função de limpeza: Quando a ref é desanexada, React chamará a função de limpeza. Se uma função não for retornada pelo callback ref, React chamará o callback novamente com null como argumento quando a ref for desanexada. Esse comportamento será removido em uma versão futura.

Ressalvas

  • Quando o Modo Strict está ativado, React irá executar um ciclo extra de configuração + limpeza apenas para desenvolvimento antes da primeira configuração real. Este é um teste de estresse que garante que sua lógica de limpeza “espelhe” sua lógica de configuração e que ele pare ou desfaça o que a configuração está fazendo. Se isso causar um problema, implemente a função de limpeza.
  • Quando você passa um callback ref diferente, React chamará a função de limpeza do callback anterior, se fornecida. Se nenhuma função de limpeza for definida, o callback ref será chamado com null como argumento. A função seguinte será chamada com o nó DOM.

Objeto de evento React

Seus manipuladores de eventos receberão um objeto de evento React. Ele também é às vezes conhecido como um “evento sintético”.

<button onClick={e => {
  console.log(e); // Objeto de evento React
}} />

Ele está em conformidade com o mesmo padrão dos eventos DOM subjacentes, mas corrige algumas inconsistências do navegador.

Alguns eventos React não se mapeiam diretamente para os eventos nativos do navegador. Por exemplo, em onMouseLeave, e.nativeEvent apontará para um evento mouseout. O mapeamento específico não faz parte da API pública e pode mudar no futuro. Se você precisar do evento do navegador subjacente por algum motivo, leia-o de e.nativeEvent.

Propriedades

Os objetos de evento React implementam algumas das propriedades Event padrão:

  • bubbles: Um booleano. Retorna se o evento se propaga pelo DOM.
  • cancelable: Um booleano. Retorna se o evento pode ser cancelado.
  • currentTarget: Um nó DOM. Retorna o nó ao qual o manipulador atual está anexado na árvore React.
  • defaultPrevented: Um booleano. Retorna se preventDefault foi chamado.
  • eventPhase: Um número. Retorna em qual fase o evento está no momento.
  • isTrusted: Um booleano. Retorna se o evento foi iniciado pelo usuário.
  • target: Um nó DOM. Retorna o nó em que o evento ocorreu (que pode ser um filho distante).
  • timeStamp: Um número. Retorna o tempo em que o evento ocorreu.

Além disso, os objetos de evento React fornecem essas propriedades:

  • nativeEvent: Um Event DOM. O objeto de evento original do navegador.

Métodos

Os objetos de evento React implementam alguns dos métodos Event padrão:

Além disso, os objetos de evento React fornecem esses métodos:

  • isDefaultPrevented(): Retorna um valor booleano indicando se preventDefault foi chamado.
  • isPropagationStopped(): Retorna um valor booleano indicando se stopPropagation foi chamado.
  • persist(): Não usado com React DOM. Com React Native, chame isso para ler as propriedades do evento após o evento.
  • isPersistent(): Não usado com React DOM. Com React Native, retorna se persist foi chamado.

Ressalvas

  • Os valores de currentTarget, eventPhase, target e type refletem os valores que seu código React espera. Por baixo dos panos, React anexa manipuladores de eventos na raiz, mas isso não é refletido em objetos de evento React. Por exemplo, e.currentTarget pode não ser o mesmo que o e.nativeEvent.currentTarget subjacente. Para eventos polyfilled, e.type (tipo de evento React) pode diferir de e.nativeEvent.type (tipo subjacente).

Função do manipulador AnimationEvent

Um tipo de manipulador de eventos para os eventos animação CSS.

<div
  onAnimationStart={e => console.log('onAnimationStart')}
  onAnimationIteration={e => console.log('onAnimationIteration')}
  onAnimationEnd={e => console.log('onAnimationEnd')}
/>

Parâmetros

Função do manipulador ClipboardEvent

Um tipo de manipulador de eventos para os eventos da API Clipboard.

<input
  onCopy={e => console.log('onCopy')}
  onCut={e => console.log('onCut')}
  onPaste={e => console.log('onPaste')}
/>

Parâmetros

Função do manipulador CompositionEvent

Um tipo de manipulador de eventos para os eventos do editor de método de entrada (IME).

<input
  onCompositionStart={e => console.log('onCompositionStart')}
  onCompositionUpdate={e => console.log('onCompositionUpdate')}
  onCompositionEnd={e => console.log('onCompositionEnd')}
/>

Parâmetros

Função do manipulador DragEvent

Um tipo de manipulador de eventos para os eventos da API HTML Drag and Drop.

<>
  <div
    draggable={true}
    onDragStart={e => console.log('onDragStart')}
    onDragEnd={e => console.log('onDragEnd')}
  >
    Origem da arrastada
  </div>

  <div
    onDragEnter={e => console.log('onDragEnter')}
    onDragLeave={e => console.log('onDragLeave')}
    onDragOver={e => { e.preventDefault(); console.log('onDragOver'); }}
    onDrop={e => console.log('onDrop')}
  >
    Alvo da soltura
  </div>
</>

Parâmetros

Função do manipulador FocusEvent

Um tipo de manipulador de eventos para os eventos de foco.

<input
  onFocus={e => console.log('onFocus')}
  onBlur={e => console.log('onBlur')}
/>

Veja um exemplo.

Parâmetros

Função do manipulador Event

Um tipo de manipulador de eventos para eventos genéricos.

Parâmetros

Função do manipulador InputEvent

Um tipo de manipulador de eventos para o evento onBeforeInput.

<input onBeforeInput={e => console.log('onBeforeInput')} />

Parâmetros

Função do manipulador KeyboardEvent

Um tipo de manipulador de eventos para eventos de teclado.

<input
  onKeyDown={e => console.log('onKeyDown')}
  onKeyUp={e => console.log('onKeyUp')}
/>

Veja um exemplo.

Parâmetros

Função do manipulador MouseEvent

Um tipo de manipulador de eventos para eventos de mouse.

<div
  onClick={e => console.log('onClick')}
  onMouseEnter={e => console.log('onMouseEnter')}
  onMouseOver={e => console.log('onMouseOver')}
  onMouseDown={e => console.log('onMouseDown')}
  onMouseUp={e => console.log('onMouseUp')}
  onMouseLeave={e => console.log('onMouseLeave')}
/>

Veja um exemplo.

Parâmetros

Função do manipulador PointerEvent

Um tipo de manipulador de eventos para eventos de ponteiro.

<div
  onPointerEnter={e => console.log('onPointerEnter')}
  onPointerMove={e => console.log('onPointerMove')}
  onPointerDown={e => console.log('onPointerDown')}
  onPointerUp={e => console.log('onPointerUp')}
  onPointerLeave={e => console.log('onPointerLeave')}
/>

Veja um exemplo.

Parâmetros

Ele também inclui as propriedades herdadas do UIEvent:

Função manipuladora de eventos TouchEvent

Um tipo de manipulador de eventos para eventos de toque.

<div
  onTouchStart={e => console.log('onTouchStart')}
  onTouchMove={e => console.log('onTouchMove')}
  onTouchEnd={e => console.log('onTouchEnd')}
  onTouchCancel={e => console.log('onTouchCancel')}
/>

Parâmetros

Função manipuladora do evento TransitionEvent

Um tipo de manipulador de eventos para os eventos de transição CSS.

<div
  onTransitionEnd={e => console.log('onTransitionEnd')}
/>

Parâmetros

Função manipuladora de eventos UIEvent

Um tipo de manipulador de eventos para eventos de UI genéricos.

<div
  onScroll={e => console.log('onScroll')}
/>

Parâmetros

Função manipuladora de eventos WheelEvent

Um tipo de manipulador de eventos para o evento onWheel.

<div
  onWheel={e => console.log('onWheel')}
/>

Parâmetros

Uso

Aplicando estilos CSS

No React, você especifica uma classe CSS com className. Ele funciona como o atributo class em HTML:

<img className="avatar" />

Então você escreve as regras CSS correspondentes em um arquivo CSS separado:

/* No seu CSS */
.avatar {
  border-radius: 50%;
}

O React não prescreve como você adiciona arquivos CSS. No caso mais simples, você adicionará uma tag <link> ao seu HTML. Se você usar uma ferramenta de build ou um framework, consulte sua documentação para aprender como adicionar um arquivo CSS ao seu projeto.

Às vezes, os valores de estilo dependem de dados. Use o atributo style para passar alguns estilos dinamicamente:

<img
  className="avatar"
  style={{
    width: user.imageSize,
    height: user.imageSize
  }}
/>

No exemplo acima, style={{}} não é uma sintaxe especial, mas um objeto {} regular dentro da style={ } chaves JSX. Recomendamos usar o atributo style apenas quando seus estilos dependem de variáveis JavaScript.

export default function Avatar({ user }) {
  return (
    <img
      src={user.imageUrl}
      alt={'Photo of ' + user.name}
      className="avatar"
      style={{
        width: user.imageSize,
        height: user.imageSize
      }}
    />
  );
}
Deep Dive

Como aplicar várias classes CSS condicionalmente?

Para aplicar classes CSS condicionalmente, você precisa produzir a string className você mesmo usando JavaScript.

Por exemplo, className={'row ' + (isSelected ? 'selected': '')} produzirá className="row" ou className="row selected" dependendo se isSelected é true.

Para tornar isso mais legível, você pode usar uma pequena biblioteca auxiliar como classnames:

import cn from 'classnames';

function Row({ isSelected }) {
  return (
    <div className={cn('row', isSelected && 'selected')}>
      ...
    </div>
  );
}

É especialmente conveniente se você tiver várias classes condicionais:

import cn from 'classnames';

function Row({ isSelected, size }) {
  return (
    <div className={cn('row', {
      selected: isSelected,
      large: size === 'large',
      small: size === 'small',
    })}>
      ...
    </div>
  );
}

Manipulando um nó DOM com uma ref

Às vezes, você precisará obter o nó DOM do navegador associado a uma tag em JSX. Por exemplo, se você deseja focar em um <input> quando um botão é clicado, você precisa chamar focus() no nó DOM <input> do navegador.

Para obter o nó DOM do navegador para uma tag, declare uma ref e passe-a como o atributo ref para essa tag:

import { useRef } from 'react';

export default function Form() {
  const inputRef = useRef(null);
  // ...
  return (
    <input ref={inputRef} />
    // ...

O React colocará o nó DOM em inputRef.current depois que ele for renderizado na tela.

import { useRef } from 'react';

export default function Form() {
  const inputRef = useRef(null);

  function handleClick() {
    inputRef.current.focus();
  }

  return (
    <>
      <input ref={inputRef} />
      <button onClick={handleClick}>
        Focus the input
      </button>
    </>
  );
}

Leia mais sobre manipulação de DOM com refs e verifique mais exemplos.

Para casos de uso mais avançados, o atributo ref também aceita uma função callback.

Definindo perigosamente o HTML interno

Você pode passar uma string HTML bruta para um elemento da seguinte forma:

const markup = { __html: '<p>some raw html</p>' };
return <div dangerouslySetInnerHTML={markup} />;

Isto é perigoso. Como acontece com a propriedade innerHTML DOM subjacente, você deve ter extrema cautela! A menos que a marcação seja proveniente de uma fonte totalmente confiável, é trivial introduzir uma vulnerabilidade XSS dessa maneira.

Por exemplo, se você usar uma biblioteca Markdown que converte Markdown em HTML, você confia que seu analisador não contenha bugs, e o usuário só vê sua própria entrada, você pode exibir o HTML resultante assim:

import { Remarkable } from 'remarkable';

const md = new Remarkable();

function renderMarkdownToHTML(markdown) {
  // Isto é SOMENTE seguro porque o HTML de saída
  // é mostrado para o mesmo usuário e porque você
  // confia que este analisador Markdown não tem bugs.
  const renderedHTML = md.render(markdown);
  return {__html: renderedHTML};
}

export default function MarkdownPreview({ markdown }) {
  const markup = renderMarkdownToHTML(markdown);
  return <div dangerouslySetInnerHTML={markup} />;
}

O objeto {__html} deve ser criado o mais próximo possível de onde o HTML é gerado, como o exemplo acima faz na função renderMarkdownToHTML. Isso garante que todo o HTML bruto que está sendo usado em seu código seja explicitamente marcado como tal e que apenas as variáveis que você espera que contenham HTML sejam passadas para dangerouslySetInnerHTML. Não é recomendado criar o objeto inline como <div dangerouslySetInnerHTML={{__html: markup}} />.

Para ver por que renderizar HTML arbitrário é perigoso, substitua o código acima por isto:

const post = {
  // Imagine que este conteúdo está armazenado no banco de dados.
  content: `<img src="" onerror='alert("você foi hackeado")'>`
};

export default function MarkdownPreview() {
  // 🔴 FURO DE SEGURANÇA: passando uma entrada não confiável para dangerouslySetInnerHTML
  const markup = { __html: post.content };
  return <div dangerouslySetInnerHTML={markup} />;
}

O código incorporado no HTML será executado. Um hacker poderia usar este furo de segurança para roubar informações do usuário ou realizar ações em seu nome. Use dangerouslySetInnerHTML apenas com dados confiáveis e sanitizados.

Manipulando eventos de mouse

Este exemplo mostra alguns eventos de mouse comuns e quando eles são disparados.

export default function MouseExample() {
  return (
    <div
      onMouseEnter={e => console.log('onMouseEnter (pai)')}
      onMouseLeave={e => console.log('onMouseLeave (pai)')}
    >
      <button
        onClick={e => console.log('onClick (primeiro botão)')}
        onMouseDown={e => console.log('onMouseDown (primeiro botão)')}
        onMouseEnter={e => console.log('onMouseEnter (primeiro botão)')}
        onMouseLeave={e => console.log('onMouseLeave (primeiro botão)')}
        onMouseOver={e => console.log('onMouseOver (primeiro botão)')}
        onMouseUp={e => console.log('onMouseUp (primeiro botão)')}
      >
        Primeiro botão
      </button>
      <button
        onClick={e => console.log('onClick (segundo botão)')}
        onMouseDown={e => console.log('onMouseDown (segundo botão)')}
        onMouseEnter={e => console.log('onMouseEnter (segundo botão)')}
        onMouseLeave={e => console.log('onMouseLeave (segundo botão)')}
        onMouseOver={e => console.log('onMouseOver (segundo botão)')}
        onMouseUp={e => console.log('onMouseUp (segundo botão)')}
      >
        Segundo botão
      </button>
    </div>
  );
}

Manipulando eventos de ponteiro

Este exemplo mostra alguns eventos de ponteiro comuns e quando eles são disparados.

export default function PointerExample() {
  return (
    <div
      onPointerEnter={e => console.log('onPointerEnter (pai)')}
      onPointerLeave={e => console.log('onPointerLeave (pai)')}
      style={{ padding: 20, backgroundColor: '#ddd' }}
    >
      <div
        onPointerDown={e => console.log('onPointerDown (primeiro filho)')}
        onPointerEnter={e => console.log('onPointerEnter (primeiro filho)')}
        onPointerLeave={e => console.log('onPointerLeave (primeiro filho)')}
        onPointerMove={e => console.log('onPointerMove (primeiro filho)')}
        onPointerUp={e => console.log('onPointerUp (primeiro filho)')}
        style={{ padding: 20, backgroundColor: 'lightyellow' }}
      >
        Primeiro filho
      </div>
      <div
        onPointerDown={e => console.log('onPointerDown (segundo filho)')}
        onPointerEnter={e => console.log('onPointerEnter (segundo filho)')}
        onPointerLeave={e => console.log('onPointerLeave (segundo filho)')}
        onPointerMove={e => console.log('onPointerMove (segundo filho)')}
        onPointerUp={e => console.log('onPointerUp (segundo filho)')}
        style={{ padding: 20, backgroundColor: 'lightblue' }}
      >
        Segundo filho
      </div>
    </div>
  );
}

Manipulando eventos de foco

No React, eventos de foco propagam. Você pode usar o currentTarget e relatedTarget para diferenciar se os eventos de foco ou desfoque se originaram de fora do elemento pai. O exemplo mostra como detectar o foco de um filho, o foco do elemento pai e como detectar a entrada ou saída do foco de toda a subárvore.

export default function FocusExample() {
  return (
    <div
      tabIndex={1}
      onFocus={(e) => {
        if (e.currentTarget === e.target) {
          console.log('foco no pai');
        } else {
          console.log('foco no filho', e.target.name);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // Não é acionado ao trocar o foco entre os filhos
          console.log('foco entrou no pai');
        }
      }}
      onBlur={(e) => {
        if (e.currentTarget === e.target) {
          console.log('pai sem foco');
        } else {
          console.log('filho sem foco', e.target.name);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // Não é acionado ao trocar o foco entre os filhos
          console.log('foco deixou o pai');
        }
      }}
    >
      <label>
        Primeiro nome:
        <input name="firstName" />
      </label>
      <label>
        Sobrenome:
        <input name="lastName" />
      </label>
    </div>
  );
}

Manipulando eventos de teclado

Este exemplo mostra alguns eventos de teclado comuns e quando eles são disparados.

export default function KeyboardExample() {
  return (
    <label>
      Primeiro nome:
      <input
        name="firstName"
        onKeyDown={e => console.log('onKeyDown:', e.key, e.code)}
        onKeyUp={e => console.log('onKeyUp:', e.key, e.code)}
      />
    </label>
  );
}
PreviousComponents
Next<form>