Referencia de la API
Componentes

Componentes comunes (p. ej. <div>)

Todos los componentes integrados, como <div>, admiten algunas props y eventos comunes.

Referencia

Componentes comunes (p. ej. <div>) 

<div className="wrapper">Algún contenido</div>

Ver más ejemplos abajo.

Props

Estas props especiales de React son compatibles con todos los componentes integrados:

  • children: Un nodo de React (un elemento, un string, un número, un portal, un nodo vacío como null, undefined y booleanos, o un array de otros nodos de React). Especifica el contenido dentro del componente. Cuando usas JSX, por lo general especificarás la prop children implícitamente mediante la anidación de etiquetas como <div><span /></div>.

  • dangerouslySetInnerHTML: Un objeto de la forma { __html: '<p>some html</p>' } con un string HTML sin procesar dentro. Anula la propiedad innerHTML del nodo del DOM y muestra el HTML pasado en el interior. Debe usarse con extrema precaución. Si el HTML no es de confianza (por ejemplo, si se basa en datos de usuario), se corre el riesgo de introducir una vulnerabilidad XSS. Lee más sobre cómo utilizar dangerouslySetInnerHTML.

  • ref: Un objeto ref de useRef o createRef, o una función callback ref, o un string para antiguas refs. Tu ref se llenará con el elemento DOM para este nodo. Lee más sobre cómo manipular el DOM con refs.

  • suppressContentEditableWarning: Un booleano. Si es true, suprime la advertencia que React muestra para los elementos que tienen tanto children como contentEditable={true} (que normalmente no funcionan juntos). Úsalo si estás construyendo una biblioteca de entrada de texto que gestiona el contenido contentEditable manualmente.

  • suppressHydrationWarning: Un booleano. Si usas renderizado en el servidor, normalmente hay una advertencia cuando el servidor y el cliente renderizan un contenido diferente. En algunos casos extraños (como marcas de tiempo), es muy difícil o incluso imposible garantizar una concidencia exacta. Si estableces suppressHydrationWarning en true, React no te advertirá sobre las inconsistencias en los atributos y el contenido de este elemento. Sólo funciona a un nivel de profundidad, y está destinado a ser utilizado como una salida de emergencia. No lo uses en exceso. Lee más sobre cómo suprimir errores de hidratación.

  • style: Un objeto con estilos CSS, por ejemplo { fontWeight: 'bold', margin: 20 }. Al igual que la propiedad style del DOM, los nombres de las propiedades CSS deben escribirse en camelCase, por ejemplo fontWeight en lugar de font-weight. Puedes pasar strings o números como valores. Si pasas un número, como width: 100, React automáticamente agregará px («píxeles») al valor a menos que sea una propiedad sin unidades. Se recomienda usar style sólo para estilos dinámicos donde no se conocen los valores de estilo de antemano. En otros casos, aplicar clases clases CSS simples con className es más eficiente. Lee más sobre className y style.

Estas propiedades DOM estándar también son compatibles con todos los componentes integrados:

  • accessKey: Un string. Especifica un acceso directo del teclado para el elemento. Generalmente no se recomienda.
  • aria-*: Los atributos ARIA te permiten especificar la información del árbol de accesibilidad para este elemento. Consulta atributos ARIA para obtener una referencia completa. En React, todos los nombres de atributos ARIA son exactamente iguales que en HTML.
  • autoCapitalize: Un string. Especifica si la entrada de texto que escribe el usuario se escribe en mayúsculas y cómo.
  • className: Un string. Especifica el nombre de la clase CSS del elemento. Lee más sobre cómo aplicar estilos de CSS.
  • contentEditable: Un booleano. Si es true, el navegador permite al usuario editar directamente el elemento renderizado. Esto se utiliza para implementar bibliotecas de entrada de texto enriquecido como Lexical. React advierte si intentas pasar children a un elemento con contentEditable={true} porque React no podrá actualizar su contenido después de que el usuario lo edite.
  • data-*: Los atributos de datos permiten adjuntar algún dato tipo string, por ejemplo data-fruit="banana". En React, comúnmente no se utilizan porque generalmente se leen datos de props o del estado en su lugar.
  • dir: 'ltr' or 'rtl'. Especifica la dirección de texto del elemento.
  • draggable: Un booleano. Especifica si el elemento puede ser arrastrado. Lee más sobre la API de arrastrar y soltar de HTML.
  • enterKeyHint: Un string. Especifica qué acción presentar para la tecla Enter de los teclados virtuales.
  • htmlFor: Un string. Para <label> y <output>, permite asociar la etiqueta con algún control. Lo mismo para el atributo HTML for. React utiliza los nombres de propiedades DOM estándar (htmlFor) en lugar de los nombres de los atributos HTML.
  • hidden: Un booleano o un string. Especifica si el elemento debe estar oculto.
  • id: Un string. Especifica un identificador único para este elemento, el cual puede ser usado para encontrarlo después o conectarlo con otros elementos. Genéralo con useId para evitar conflictos entre varias instancias del mismo componente.
  • is: Un string. Si se especifica, el componente se comportará como un elemento personalizado.
  • inputMode: Un string. Especifica qué tipo de teclado mostrar (por ejemplo, texto, número o teléfono).
  • itemProp: Un string. Especifica cuál propiedad representa el elemento para los rastreadores de datos estructurados.
  • lang: Un string. Especifica el idioma del elemento.
  • onAnimationEnd: Una función controladora de evento AnimationEvent. Se dispara cuando una animación de CSS se completa.
  • onAnimationEndCapture: Una versión de onAnimationEnd que se dispara en la fase de captura.
  • onAnimationIteration: Una función controladora de evento AnimationEvent. Se dispara cuando una iteración de una animación de CSS termina y comienza otra.
  • onAnimationIterationCapture: Una versión de onAnimationIteration que se dispara en la fase de captura
  • onAnimationStart: Una función controladora de evento AnimationEvent. Se dispara cuando una animación de CSS comienza.
  • onAnimationStartCapture: onAnimationStart, pero se dispara en la fase de captura.
  • onAuxClick: Una función controladora de evento MouseEvent. Se dispara cuando se hace clic en un botón no primario.
  • onAuxClickCapture: Una versión de onAuxClick que se dispara en la fase de captura.
  • onBeforeInput: Una función controladora de evento InputEvent. Se dispara antes de que se modifique el valor de un elemento editable. React aún no utiliza el evento nativo beforeinput, sino que intenta emularlo utilizando otros eventos.
  • onBeforeInputCapture: Una versión de onBeforeInput que se dispara en la fase de captura.
  • onBlur: Una función controladora de evento FocusEvent. Se dispara cuando un elemento pierde el foco. A diferencia del evento blur integrado en el navegador, en React, el evento onBlur se propaga.
  • onBlurCapture: Una versión de onBlur que se dispara en la fase de captura.
  • onClick: Una función controladora de evento MouseEvent. Se dispara cuando se hace clic en el botón principal del dispositivo señalador.
  • onClickCapture: Una versión de onClick que se dispara en la fase de captura.
  • onCompositionStart: Una función controladora de evento CompositionEvent. Se dispara cuando un editor de método de entrada comienza una nueva sesión de composición.
  • onCompositionStartCapture: Una versión de onCompositionStart que se dispara en la fase de captura.
  • onCompositionEnd: Una función controladora de evento CompositionEvent. Se dispara cuando un editor de métodos de entrada completa o cancela una sesión de composición.
  • onCompositionEndCapture: Una versión de onCompositionEnd que se dispara en la fase de captura.
  • onCompositionUpdate: Una función controladora de evento CompositionEvent. Se dispara cuando un editor de métodos de entrada recibe un nuevo carácter.
  • onCompositionUpdateCapture: Una versión de onCompositionUpdate que se dispara en la fase de captura.
  • onContextMenu: Una función controladora de evento MouseEvent. Se dispara cuando el usuario intenta abrir un menú contextual.
  • onContextMenuCapture: Una versión de onContextMenu que se dispara en la fase de captura.
  • onCopy: Una función controladora de evento ClipboardEvent. Se dispara cuando el usuario intenta copiar algo en el portapapeles.
  • onCopyCapture: Una versión de onCopy que se dispara en la fase de captura.
  • onCut: Una función controladora de evento ClipboardEvent. Se dispara cuando el usuario intenta cortar algo en el cortapapeles.
  • onCutCapture: Una versión de onCut que se dispara en la fase de captura.
  • onDoubleClick: Una función controladora de evento MouseEvent. Se dispara cuando el usuario hace doble click. Corresponde al evento dblclick del navegador.
  • onDoubleClickCapture: Una versión de onDoubleClick que se dispara en la fase de captura.
  • onDrag: Una función controladora de evento DragEvent. Se dispara mientras el usuario arrastra algo.
  • onDragCapture: Una versión de onDrag que se dispara en la fase de captura.
  • onDragEnd: Una función controladora de evento DragEvent. Se dispara cuando el usuario deja de arrastrar algo.
  • onDragEndCapture: Una versión de onDragEnd que se dispara en la fase de captura.
  • onDragEnter: Una función controladora de evento DragEvent. Se dispara cuando el contenido arrastrado entra en un objetivo válido para soltarlo.
  • onDragEnterCapture: Una versión de onDragEnter que se dispara en la fase de captura.
  • onDragOver: Una función controladora de evento DragEvent. Se dispara en un objetivo de soltar válido mientras el contenido arrastrado está sobre él. Debes llamar e.preventDefault() aquí para permitir soltar.
  • onDragOverCapture: Una versión de onDragOver que se dispara en la fase de captura.
  • onDragStart: Una función controladora de evento DragEvent. Se dispara cuando el usuario comienza a arrastrar un elemento.
  • onDragStartCapture: Una versión de onDragStart que se dispara en la fase de captura.
  • onDrop: Una función controladora de evento DragEvent. Se dispara cuando se suelta algo en un objetivo de soltar válido.
  • onDropCapture: Una versión de onDrop que se dispara en la fase de captura.
  • onFocus: A FocusEvent. Se dispara cuando un elemento recibe el foco. A diferencia del evento de focus integrado del navegador, en React el evento onFocus se propaga.
  • onFocusCapture: Una versión de onFocus que se dispara en la fase de captura.
  • onGotPointerCapture: Una función controladora de evento PointerEvent. Se dispara cuando un elemento captura un puntero.
  • onGotPointerCaptureCapture: Una versión de onGotPointerCapture que se dispara en la fase de captura.
  • onKeyDown: Una función controladora de evento KeyboardEvent. Se dispara cuando una tecla es presionada.
  • onKeyDownCapture: Una versión de onKeyDown que se dispara en la fase de captura.
  • onKeyPress: Una función controladora de evento KeyboardEvent. Obsoleta. En su lugar, usa onKeyDown o onBeforeInput.
  • onKeyPressCapture: Una versión de onKeyPress que se dispara en la fase de captura.
  • onKeyUp: Una función controladora de evento KeyboardEvent. Se dispara cuando se suelta una tecla.
  • onKeyUpCapture: Una versión de onKeyUp que se dispara en la fase de captura.
  • onLostPointerCapture: Una función controladora de evento PointerEvent. Se dispara cuando un elemento deja de capturar un puntero.
  • onLostPointerCaptureCapture: Una versión de onLostPointerCapture que se dispara en la fase de captura.
  • onMouseDown: Una función controladora de evento MouseEvent. Se dispara cuando el puntero se presiona.
  • onMouseDownCapture: Una versión de onMouseDown que se dispara en la fase de captura.
  • onMouseEnter: Una función controladora de evento MouseEvent. Se dispara cuando el puntero se mueve dentro de un elemento. No tiene una fase de captura. , onMouseLeave y onMouseEnter se propagan desde el elemento que se deja al que se ingresa.
  • onMouseLeave: Una función controladora de evento MouseEvent. Se dispara cuando el puntero se mueve fuera de un elemento. No tiene una fase de captura. En su lugar, onMouseLeave y onMouseEnter se propagan desde el elemento que se deja al que se ingresa.
  • onMouseMove: Una función controladora de evento MouseEvent. Se dispara cuando el puntero cambia de coordenadas.
  • onMouseMoveCapture: Una versión de onMouseMove que se dispara en la fase de captura.
  • onMouseOut: Una función controladora de evento MouseEvent. Se dispara cuando el puntero se mueve fuera de un elemento, o si se mueve a un elemento hijo.
  • onMouseOutCapture: Una versión de onMouseOut que se dispara en la fase de captura.
  • onMouseUp: Una función controladora de evento MouseEvent. Se dispara cuando se suelta el puntero.
  • onMouseUpCapture: Una versión de onMouseUp que se dispara en la fase de captura.
  • onPointerCancel: Una función controladora de evento PointerEvent. Se dispara cuando el navegador cancela una interacción de puntero.
  • onPointerCancelCapture: Una versión de onPointerCancel que se dispara en la fase de captura.
  • onPointerDown: Una función controladora de evento PointerEvent. Se dispara cuando el puntero se vuelve activo.
  • onPointerDownCapture: Una versión de onPointerDown que se dispara en la fase de captura.
  • onPointerEnter: Una función controladora de evento PointerEvent. Se dispara cuando un cursor se mueve dentro de un elemento. No tiene una fase de captura. En su lugar, onPointerLeave y onPointerEnter se propagan desde el elemento que se deja al que se ingresa.
  • onPointerLeave: Una función controladora de evento PointerEvent. Se dispara cuando un puntero se mueve fuera de un elemento. No tiene una fase de captura. En su lugar, onPointerLeave y onPointerEnter se propagan desde el elemento que se deja al que se ingresa.
  • onPointerMove: Una función controladora de evento PointerEvent. Se dispara cuando un puntero cambia de coordenadas.
  • onPointerMoveCapture: Una versión de onPointerMove que se dispara en la fase de captura.
  • onPointerOut: Una función controladora de evento PointerEvent. Se dispara cuando un puntero se mueve fuera de un elemento, si la interacción del puntero es cancelada, y por algunas otras razones.
  • onPointerOutCapture: Una versión de onPointerOut que se dispara en la fase de captura.
  • onPointerUp: Una función controladora de evento PointerEvent. Se dispara cuando un puntero ya no está activo.
  • onPointerUpCapture: Una versión de onPointerUp que se dispara en la fase de captura.
  • onPaste: Una función controladora de evento ClipboardEvent. Se dispara cuando el usuario intenta pegar algo desde el portapapeles.
  • onPasteCapture: Una versión de onPaste que se dispara en la fase de captura.
  • onScroll: Una función controladora de evento Event. Se dispara cuando se ha desplazado un elemento. Este evento no se propaga.
  • onScrollCapture: Una versión de onScroll que se dispara en la fase de captura.
  • onSelect: Una función controladora de evento Event. Se dispara después de que la selección dentro de un elemento editable, como un input, cambia. React extiende el evento onSelect para que funcione también en elementos con contentEditable={true}. Además, React lo extiende para que se active cuando la selección esté vacía y en ediciones (que pueden afectar la selección).
  • onSelectCapture: Una versión de onSelect que se dispara en la fase de captura.
  • onTouchCancel: Una función controladora de evento TouchEvent. Se dispara cuando el navegador cancela una interacción táctil.
  • onTouchCancelCapture: Una versión de onTouchCancel que se dispara en la fase de captura.
  • onTouchEnd: Una función controladora de evento TouchEvent. Se dispara cuando se quitan uno o más puntos táctiles.
  • onTouchEndCapture: Una versión de onTouchEnd que se dispara en la fase de captura.
  • onTouchMove: Una función controladora de evento TouchEvent. Se dispara cuando se mueven uno o más puntos táctiles.
  • onTouchMoveCapture: Una versión de onTouchMove que se dispara en la fase de captura.
  • onTouchStart: Una función controladora de evento TouchEvent. Se dispara cuando se colocan uno más puntos táctiles
  • onTouchStartCapture: Una versión de onTouchStart que se dispara en la fase de captura.
  • onTransitionEnd: Una función controladora de evento TransitionEvent. Se dispara cuando se completa una transición de CSS.
  • onTransitionEndCapture: Una versión de onTransitionEnd que se dispara en la fase de captura.
  • onWheel: Una función controladora de evento WheelEvent. Se dispara cuando el usuario gira un botón de rueda en un dispositivo señalador.
  • onWheelCapture: Una versión de onWheel que se dispara en la fase de captura.
  • role: Un string. Especifica el rol del elemento explícitamente para las tecnologías de asistencia.
  • slot: Un string. Especifica el nombre del slot cuando se utiliza shadow DOM. En React, normalmente se logra un patrón equivalente al pasar JSX como props, por ejemplo <Layout left={<Sidebar />} right={<Content />} />.
  • spellCheck: Un booleano o null. Si explícitamente se establece en true o false, habilita o deshabilita la corrección ortográfica.
  • tabIndex: Un número. Anula el comportamiento por defecto del botón Tab. Evita utilizar valores distintos de -1 y 0.
  • title: Un string. Especifica el texto de información de ayuda para el elemento.
  • translate: Ya sea 'yes' o 'no'. Pasar 'no' excluye el contenido del elemento de ser traducido.

También puedes pasar atributos personalizados como props, por ejemplo mycustomprop="someValue". Esto puede ser útil al integrar bibliotecas de terceros. El nombre del atributo personalizado debe estar en minúsculas y no debe empezar con on. El valor se convertirá a un string. Si pasas null o undefined, se eliminará el atributo personalizado.

Estos eventos se disparan sólo para los elementos <form>:

  • onReset: Una función controladora de evento Event. Se dispara cuando se reinicia un formulario.
  • onResetCapture: Una versión de onReset que se dispara en la fase de captura.
  • onSubmit: Una función controladora de evento Event. Se dispara cuando se envía un formulario.
  • onSubmitCapture: Una versión de onSubmit que se dispara en la fase de captura.

Estos eventos se disparan sólo para los elementos <dialog>. A diferencia de los eventos del navegador, se propagan en React:

  • onCancel: Una función controladora de evento Event. Se dispara cuando el usuario intenta cerrar el diálogo.
  • onCancelCapture: Una versión de onCancel que se dispara en la fase de captura.
  • onClose: Una función controladora de evento Event. Se dispara cuando un diálogo ha sido cerrado.
  • onCloseCapture: Una versión de onClose que se dispara en la fase de captura.

Estos eventos sólo se disparan para los elementos <details>. A diferencia de los eventos del navegador, se propagan en React:

  • onToggle: Una función controladora de evento Event. Se dispara cuando el usuario cambia el estado de los detalles.
  • onToggleCapture: Una versión de onToggle que se dispara en la fase de captura.

Estos eventos se disparan para los elementos <img>, <iframe>, <object>, <embed>, <link>, and SVG <image>. A diferencia de los eventos del navegador, se propagan en React:

  • onLoad: Una función controladora de evento Event. Se dispara cuando el recurso ha sido cargado.
  • onLoadCapture: Una versión de onLoad que se dispara en la fase de captura.
  • onError: Una función controladora de evento Event. Se dispara cuando el recurso no se ha podido cargar.
  • onErrorCapture: Una versión de onError que se dispara en la fase de captura.

Estos eventos se disparan para recursos como <audio> y <video>. A diferencia de los eventos del navegador, se propagan en React:

  • onAbort: Una función controladora de evento Event. Se dispara cuando el recurso no se ha cargado completamente, pero no debido a un error.
  • onAbortCapture: Una versión de onAbort que se dispara en la fase de captura.
  • onCanPlay: Una función controladora de evento Event. Se dispara cuando hay suficientes datos para empezar a reproducir, pero no los suficientes para reproducir hasta el final sin búfer.
  • onCanPlayCapture: Una versión de onCanPlay que se dispara en la fase de captura.
  • onCanPlayThrough: Una función controladora de evento Event. Se dispara cuando hay suficientes datos y es posible empezar a reproducir sin búfer hasta el final.
  • onCanPlayThroughCapture: Una versión de onCanPlayThrough que se dispara en la fase de captura.
  • onDurationChange: Una función controladora de evento Event. Se dispara cuando la duración del archivo multimedia ha sido actualizada.
  • onDurationChangeCapture: Una versión de onDurationChange que se dispara en la fase de captura.
  • onEmptied: Una función controladora de evento Event. Se dispara cuando el recurso multimedia se ha quedado vacío.
  • onEmptiedCapture: Una versión de onEmptied que se dispara en la fase de captura.
  • onEncrypted: Una función controladora de evento Event. Se dispara cuando el navegador encuentra contenido multimedia encriptado.
  • onEncryptedCapture: Una versión de onEncrypted que se dispara en la fase de captura.
  • onEnded: Una función controladora de evento Event. Se dispara cuando la reproducción se detiene porque no hay nada más que reproducir.
  • onEndedCapture: Una versión de onEnded que se dispara en la fase de captura.
  • onError: Una función controladora de evento Event function. Se dispara cuando no se ha podido cargar el recurso.
  • onErrorCapture: Una versión de onError que se dispara en la fase de captura.
  • onLoadedData: Una función controladora de evento Event. Se dispara cuando el marco de reproducción actual se ha cargado.
  • onLoadedDataCapture: Una versión de onLoadedData que se dispara en la fase de captura.
  • onLoadedMetadata: Una función controladora de evento Event. Se dispara cuando se han cargado los metadatos.
  • onLoadedMetadataCapture: Una versión de onLoadedMetadata que se dispara en la fase de captura.
  • onLoadStart: Una función controladora de evento Event. Se dispara cuando el navegador ha comenzado a cargar el recurso.
  • onLoadStartCapture: Una versión de onLoadStart que se dispara en la fase de captura.
  • onPause: Una función controladora de evento Event. Se dispara cuando se ha pausado el recurso multimedia.
  • onPauseCapture: Una versión de onPause que se dispara en la fase de captura.
  • onPlay: Una función controladora de evento Event. Se dispara cuando se ha reanudado la reproducción del recurso multimedia.
  • onPlayCapture: Una versión de onPlay que se dispara en la fase de captura.
  • onPlaying: Una función controladora de evento Event. Se dispara cuando el archivo multimedia comienza o reinicia la reproducción.
  • onPlayingCapture: Una versión de onPlaying que se dispara en la fase de captura.
  • onProgress: Una función controladora de evento Event. Se dispara periódicamente mientras se está cargando el recurso.
  • onProgressCapture: Una versión de onProgress que se dispara en la fase de captura.
  • onRateChange: Una función controladora de evento Event. Se dispara cuando la velocidad de reproducción cambia.
  • onRateChangeCapture: Una versión de onRateChange que se dispara en la fase de captura.
  • onResize: Una función controladora de evento Event. Se activa cuando cambia el tamaño del video.
  • onResizeCapture: Una versión de onResize que se dispara en la fase de captura.
  • onSeeked: Una función controladora de evento Event. Se dispara cuando se completa una operación de búsqueda.
  • onSeekedCapture: Una versión de onSeeked que se dispara en la fase de captura.
  • onSeeking: Una función controladora de evento Event. Se dispara cuando comienza una operación de búsqueda.
  • onSeekingCapture: Una versión de onSeeking que se dispara en la fase de captura.
  • onStalled: Una función controladora de evento Event. Se dispara cuando el navegador está esperando datos pero no los carga.
  • onStalledCapture: Una versión de onStalled que se dispara en la fase de captura.
  • onSuspend: Una función controladora de evento Event. Se dispara cuando la carga del recurso se ha suspendido.
  • onSuspendCapture: Una versión de onSuspend que se dispara en la fase de captura.
  • onTimeUpdate: Una función controladora de evento Event. Se dispara cuando el tiempo actual de la reproducción se actualiza.
  • onTimeUpdateCapture: Una versión de onTimeUpdate que se dispara en la fase de captura.
  • onVolumeChange: Una función controladora de evento Event. Se dispara cuando el volumen ha cambiado.
  • onVolumeChangeCapture: Una versión de onVolumeChange que se dispara en la fase de captura.
  • onWaiting: Una función controladora de evento Event. Se dispara cuando la reproducción se detuvo debido a la falta temporal de datos.
  • onWaitingCapture: Una versión de onWaiting que se dispara en la fase de captura.

Advertencias

  • No puedes pasar tanto children como dangerouslySetInnerHTML al mismo tiempo.
  • Algunos eventos (como onAbort y onLoad) no se propagan en el navegador, pero sí en React.

Función callback ref

En lugar de un objeto ref (como el devuelto por useRef), puedes pasar una función al atributo ref.

<div ref={(node) => console.log(node)} />

Vea un ejemplo de la función callback ref.

Cuando el nodo del DOM <div> es agregado a la pantalla, React llamará a tu callback ref con el nodo del DOM como argumento. Cuando ese nodo del DOM <div> se elimina, React llamará a tu callback ref con null.

React también llamará a tu callback ref cada vez que pases un callback ref diferente. En el ejemplo anterior, (node) => { ... } es una función diferente en cada renderizado. Cuando tu componente se vuelva a renderizar, la función anterior será llamada con null como argumento, y la siguiente función será llamada con el nodo del DOM.

Parámetros

  • node: Un nodo del DOM o null. React te pasará el nodo del DOM cuando se vincule la ref, y null cuando la ref se desvincule. A menos que pases la misma función ref para el callback ref en cada renderizado, el callback se desprenderá temporalmente y se volverá a vincular durante cada renderizado del componente.

Devuelve

No devuelve nada desde el callback ref.

Objeto de evento de React

Los controladores de eventos recibirán un objeto de evento de React. A veces también se le conoce como un «evento sintético».

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

Cumple con el mismo estándar que los eventos DOM subyacentes, pero soluciona algunas inconsistencia del navegador.

Algunos eventos de React no se asignan directamente a los eventos nativos del navegador. Por ejemplo en onMouseLeave, e.nativeEvent apuntará a un evento mouseout. La asignación específica no forma parte de la API pública y puede cambiar en el futuro. Si necesitas el evento del navegador subyacente por alguna razón, léelo desde e.nativeEvent.

Propiedades

Los objetos de evento de React implementan algunas de las propiedades estándar de Evento:

  • bubbles: Un booleano. Devuelve si el evento se propaga a través del DOM.
  • cancelable: Un booleano. Devuelve si el evento se puede cancelar.
  • currentTarget: Un nodo del DOM. Devuelve el nodo al que se vincula el controlador de evento actual en el árbol de React.
  • defaultPrevented: Un booleano. Devuelve si se llamó a preventDefault.
  • eventPhase: Un número. Devuelve en qué fase se encuentra el evento actualmente.
  • isTrusted: Un booleano. Devuelve si el evento fue iniciado por el usuario.
  • target: Un nodo del DOM. Devuelve el nodo en el que ha ocurrido el evento (que podría ser un hijo distante)
  • timeStamp: Un número. Devuelve la hora (en milisegundos) en la que ocurrió el evento.

Además, los objetos de evento de React proporcionan estas propiedades:

  • nativeEvent: Un Evento del DOM. El objeto de evento original del navegador.

Métodos

Los objetos de evento de React implementan algunos de los métodos estándar de Evento:

  • preventDefault(): Evita la acción del navegador predeterminada para el evento.
  • stopPropagation(): Detiene la propagación del evento a través del árbol de React.

Además, los objetos de evento de React proporcionan estos métodos:

  • isDefaultPrevented(): Devuelve un valor booleano que indica si se llamó a preventDefault.
  • isPropagationStopped(): Devuelve un valor booleano que indica si se llamó a stopPropagation.
  • persist(): No se usa con React DOM. Con React Native, llámalo para leer las propiedades del evento después del evento.
  • isPersistent(): No se usa con React DOM. Con React Native, devuelve si se ha llamado a persist.

Advertencias

  • Los valores de currentTarget, eventPhase, target, y type reflejan los valores que tu código de React espera. Sin embargo, internamente, React vincula los controladores de eventos en la raíz, pero esto no se refleja en los objetos de evento de React. Por ejemplo, e.currentTarget puede no ser lo mismo que el valor subyacente e.nativeEvent.currentTarget. Para eventos con polyfills, e.type (tipo de evento de React) puede ser diferente de e.nativeEvent.type (tipo subyacente).

función controladora de evento AnimationEvent

Un tipo de controlador de evento para los eventos de animación CSS.

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

Parámetros

función controladora de evento ClipboardEvent

Un tipo de controlador de evento para los eventos de Clipboard API.

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

Parámetros

función controladora de evento CompositionEvent

Un tipo de controlador de evento para los eventos del editor de métodos de entrada.

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

Parámetros

función controladora de evento DragEvent

Un tipo de controlador de evento para los eventos de la API de arrastrar y soltar de HTML.

<>
  <div
    draggable={true}
    onDragStart={e => console.log('onDragStart')}
    onDragEnd={e => console.log('onDragEnd')}
  >
    Fuente de arrastre
  </div>

  <div
    onDragEnter={e => console.log('onDragEnter')}
    onDragLeave={e => console.log('onDragLeave')}
    onDragOver={e => { e.preventDefault(); console.log('onDragOver'); }}
    onDrop={e => console.log('onDrop')}
  >
    Área de destino
  </div>
</>

Parámetros

función controladora de evento FocusEvent

Un tipo de controlador de evento para los eventos de foco.

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

Mira un ejemplo.

Parámetros

función controladora de evento Event

Un tipo de función controladora de evento genéricos.

Parámetros

función controladora de evento InputEvent

Un tipo de controlador de evento para el evento onBeforeInput.

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

Parámetros

función controladora de evento KeyboardEvent

Un tipo de controlador de evento para eventos de teclado.

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

Mira un ejemplo.

Parámetros

función controladora de evento MouseEvent

Un tipo de controlador de evento para eventos del 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')}
/>

Mira un ejemplo.

Parámetros

función controladora de evento PointerEvent

Un tipo de controlador de evento para eventos del puntero.

<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')}
/>

Mira un ejemplo.

Parámetros

función controladora de evento TouchEvent

Un tipo de controlador de evento para eventos táctiles.

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

Parámetros

función controladora de evento TransitionEvent

Un tipo de controlador de evento para los eventos de transición CSS.

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

Parámetros

función controladora de evento UIEvent

Un tipo de controlador de evento para eventos de UI genéricos.

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

Parámetros

función controladora de evento WheelEvent

Un tipo de controlador de evento para el evento onWheel.

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

Parámetros

Uso

Aplicar estilos CSS

En React, se especifica una clase de CSS con className. Funciona como el atributo classen HTML:

<img className="avatar" />

Luego, se escriben las reglas CSS para dicha clase en un archivo CSS separado.

/* En tu archivo CSS */
.avatar {
  border-radius: 50%;
}

React no indica cómo agregar archivos CSS. En el caso más simple, añadirás una etiqueta <link> en el HTML. Si usas un framework o alguna herramienta de compilación, consulta su documentación para aprender cómo añadir un archivo CSS a tu proyecto.

A veces, los valores de estilo dependen de los datos. Usa el atributo style para pasar algunos estilos dinámicamente:

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

En el ejemplo anterior, style={{}} no es una sintaxis especial, sino un objeto {} regular dentro de las llaves JSX style={ }. Recomendamos utilizar el atributo style sólo cuando los estilos dependen de variables 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
      }}
    />
  );
}
Profundizar

¿Cómo aplicar múltiples clases de CSS de forma condicional?

Para aplicar clases de CSS de forma condicional, necesitas producir el string de className tú mismo utilizando JavaScript.

Por ejemplo, className={'row ' + (isSelected ? 'selected': '')} producirá ya sea className="row" o className="row selected" dependiendo de si isSelected es true.

Para hacer esto más legible, puedes usar una pequeña biblioteca de ayuda como classnames:

import cn from 'classnames';

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

Es conveniente si tienes múltiples clases condicionales:

import cn from 'classnames';

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

Manipular un nodo del DOM con una ref

A veces, necesitarás obtener el nodo del DOM del navegador asociado con una etiqueta en JSX. Por ejemplo, si quieres enfocar un <input> cuando se hace clic en un botón, necesitas llamar a focus() en el nodo del DOM <input> del navegador.

Para obtener el nodo del DOM del navegador de una etiqueta, declara una ref y pásala como el atributo ref a esa etiqueta:

import { useRef } from 'react';

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

React pondrá el nodo del DOM en inputRef.current después de que haya sido renderizado en la pantalla.

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>
    </>
  );
}

Lee más sobre cómo manipular el DOM con refs y consulta más ejemplos.

Para casos de uso más avanzados, el atributo ref también acepta una función callback.

dangerouslySetInnerHTML

Puedes pasar un string HTML sin procesar a un elemento de esta manera:

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

Esto es peligroso. Al igual que con la propiedad subyacente del DOM innerHTML, debes tener precaución extrema! A menos que el markup venga de una fuente completamente confiable, se podría correr el riesgo de introducir una vulnerabilidad XSS de esta manera.

Por ejemplo, si utilizas una biblioteca de Markdown que convierte Markdown a HTML, debes confiar en que el parser no contenga errores y el usuario sólo vea su propio input, puedes mostrar el HTML resultante de esta manera:

import { Remarkable } from 'remarkable';

const md = new Remarkable();

function renderMarkdownToHTML(markdown) {
  // Esto SÓLO es seguro porque el HTML resultante
  // se muestra al mismo usuario y confías en que
  // este parser de Markdown no tiene errores.
  const renderedHTML = md.render(markdown);
  return {__html: renderedHTML};
}

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

El objeto {__html} debe ser creado tan cerca a donde se genera el HTML como sea posible, como el ejemplo de arriba lo hace en la función renderMarkdownToHTML. Esto garantiza que todo el HTML sin procesar que se usa en tu código se marque explícitamente como tal, y que solo variables que esperas que contengan HTML se pasen a dangerouslySetInnerHTML. No se recomienda crear el objeto en línea de esta forma: <div dangerouslySetInnerHTML={{__html: markup}} />.

Para entender por qué el renderizado arbitrario de HTML es peligroso, reemplaza el código anterior con esto:

const post = {
  // // Imagina que este contenido se almacena en la base de datos.
  content: `<img src="" onerror='alert("has sido hackeado")'>`
};

export default function MarkdownPreview() {
  // 🔴  AGUJERO DE SEGURIDAD: pasando input no confiable a dangerouslySetInnerHTML.
  const markup = { __html: post.content };
  return <div dangerouslySetInnerHTML={markup} />;
}

El código incrustado en el HTML se ejecutará. Un hacker podría utilizar este agujero de seguridad para robar información de los usuarios o realizar acciones en su nombre. Solo usa dangerouslySetInnerHTML con datos confiables y sanitizados.

Control de eventos del mouse

Este ejemplo muestra algunos eventos del mouse comunes y cuándo se disparan.

export default function MouseExample() {
  return (
    <div
      onMouseEnter={e => console.log('onMouseEnter (parent)')}
      onMouseLeave={e => console.log('onMouseLeave (parent)')}
    >
      <button
        onClick={e => console.log('onClick (first button)')}
        onMouseDown={e => console.log('onMouseDown (first button)')}
        onMouseEnter={e => console.log('onMouseEnter (first button)')}
        onMouseLeave={e => console.log('onMouseLeave (first button)')}
        onMouseOver={e => console.log('onMouseOver (first button)')}
        onMouseUp={e => console.log('onMouseUp (first button)')}
      >
        First button
      </button>
      <button
        onClick={e => console.log('onClick (second button)')}
        onMouseDown={e => console.log('onMouseDown (second button)')}
        onMouseEnter={e => console.log('onMouseEnter (second button)')}
        onMouseLeave={e => console.log('onMouseLeave (second button)')}
        onMouseOver={e => console.log('onMouseOver (second button)')}
        onMouseUp={e => console.log('onMouseUp (second button)')}
      >
        Second button
      </button>
    </div>
  );
}

Control de eventos del puntero

Este ejemplo muestra algunos eventos del puntero comunes y cuándo se disparan.

export default function PointerExample() {
  return (
    <div
      onPointerEnter={e => console.log('onPointerEnter (parent)')}
      onPointerLeave={e => console.log('onPointerLeave (parent)')}
      style={{ padding: 20, backgroundColor: '#ddd' }}
    >
      <div
        onPointerDown={e => console.log('onPointerDown (first child)')}
        onPointerEnter={e => console.log('onPointerEnter (first child)')}
        onPointerLeave={e => console.log('onPointerLeave (first child)')}
        onPointerMove={e => console.log('onPointerMove (first child)')}
        onPointerUp={e => console.log('onPointerUp (first child)')}
        style={{ padding: 20, backgroundColor: 'lightyellow' }}
      >
        First child
      </div>
      <div
        onPointerDown={e => console.log('onPointerDown (second child)')}
        onPointerEnter={e => console.log('onPointerEnter (second child)')}
        onPointerLeave={e => console.log('onPointerLeave (second child)')}
        onPointerMove={e => console.log('onPointerMove (second child)')}
        onPointerUp={e => console.log('onPointerUp (second child)')}
        style={{ padding: 20, backgroundColor: 'lightblue' }}
      >
        Second child
      </div>
    </div>
  );
}

Control de eventos de foco

En React, los eventos de foco se propagan. Puedes usar el currentTarget y relatedTarget para diferenciar si los eventos de enfoque o desenfoque se originaron fuera del elemento padre. El ejemplo muestra cómo detectar el enfoque en un hijo, el enfoque en el elemento padre, y cómo detectar el enfoque al entrar o salir de todo el subárbol.

export default function FocusExample() {
  return (
    <div
      tabIndex={1}
      onFocus={(e) => {
        if (e.currentTarget === e.target) {
          console.log('focused parent');
        } else {
          console.log('focused child', e.target.name);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // No se activa al cambiar el enfoque entre los hijos
          console.log('focus entered parent');
        }
      }}
      onBlur={(e) => {
        if (e.currentTarget === e.target) {
          console.log('unfocused parent');
        } else {
          console.log('unfocused child', e.target.name);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // No se activa al cambiar el enfoque entre los hijos
          console.log('focus left parent');
        }
      }}
    >
      <label>
        Nombre:
        <input name="firstName" />
      </label>
      <label>
        Apellido:
        <input name="lastName" />
      </label>
    </div>
  );
}

Control de eventos de teclado

Este ejemplo muestra algunos eventos del teclado comunes y cuándo se disparan.

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

¿Qué te parece esta documentación?