Eventos de Ratón

Maneja clics, doble clic, pasos del ratón y movimiento del ratón en componentes React.

Referencia de Eventos de Ratón

Receta

Tarjeta de referencia rápida -- lista para copiar y pegar.

// Manejador de clic con evento tipado
function ClickExample() {
  const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
    console.log("Haz clic en", e.clientX, e.clientY);
  };
 
  return <button onClick=

Cuándo usarlo: Necesitas responder a interacciones del ratón -- clics, pasos del ratón, clics derechos o rastreo de posición -- en un componente cliente.

Ejemplo Funcional

"use client";
 
import { useState, useRef, useCallback } from "react";
 
type ContextMenuState = {
  visible: boolean;
  x: number;
  y: number;
};
 
export default function InteractiveCard

Lo que esto demuestra:

• Combinación de onClick, onMouseEnter, onMouseLeave y onContextMenu en un solo elemento
• Posicionamiento de un menú contextual personalizado relativo a la tarjeta usando getBoundingClientRect
• Usando e.stopPropagation() para prevenir que los clics de elementos del menú disparen el manejador de clic de la tarjeta
• Usando e.preventDefault() en onContextMenu para suprimir el menú predeterminado del navegador
• Tipado de TypeScript para estado, refs y manejadores de eventos

Inmersión Profunda

Cómo Funciona

• React normaliza eventos de ratón a través de su sistema de Eventos Sintéticos. Cada manejador de eventos de ratón recibe un React.MouseEvent<T> que envuelve el MouseEvent nativo con una interfaz consistente entre navegadores.
• React usa delegación de eventos -- un único listener se adjunta en la raíz, no en cada elemento. Tu manejador se invoca durante la fase de burbuja por defecto.
• onMouseEnter y onMouseLeave NO se propagan. Se disparan solo para el elemento exacto, no sus hijos. Usa onMouseOver y onMouseOut si necesitas comportamiento de propagación.
• El Evento Sintético se agrupa y se reutiliza. Si necesitas acceder al evento de forma asincrónica (por ejemplo, en un setTimeout), lee primero los valores que necesitas en variables locales.

Variaciones

Clic con paso de datos:

type Item = { id: string; name: string };
 
function ItemList({ items }: { items: Item[] }) {
  const handleClick = (item: Item) =>

Rastreo de pasos del ratón con coordenadas:

function HoverTracker() {
  const [position, setPosition] = useState({ x: 0, y: 0 });
 
  const handleMouseMove = useCallback(
    (e: React.MouseEvent<HTMLDivElement>) =>

Detección de arrastre inicial (mousedown + threshold de mousemove):

function DragDetector() {
  const startPos = useRef<{ x: number; y: number } | null>(null);
  const [dragging, setDragging] = useState(false);

Detección de pulsación larga:

function LongPressButton({ onLongPress }: { onLongPress: () => void }) {
  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
  const handleMouseDown = () 

Menú contextual de clic derecho con portal:

import { createPortal } from "react-dom";
 
function ContextMenuPortal({
  x,
  y,
  onClose,
}: {
  x: number;
  y: number;
  onClose: () =>

Notas de TypeScript

// El genérico T especifica el tipo de elemento para e.currentTarget
const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
  e.currentTarget; // HTMLButtonElement -- el elemento al que se adjunta el manejador
  e.target;        // EventTarget -- el elemento realmente hecho clic (podría ser un hijo)
};
 
// Usa HTMLElement como fallback genérico cuando el elemento exacto varía
const handleAny = (e

Problemas

• onMouseEnter/onMouseLeave vs onMouseOver/onMouseOut -- onMouseEnter y onMouseLeave NO se propagan y NO se disparan al moverse entre elementos hijos. onMouseOver y onMouseOut SÍ se propagan, por lo que se disparan al entrar/salir de hijos también. Usar el par incorrecto y los estados de pasos del ratón parpadearán en elementos anidados.

• Crear nuevas funciones flecha en JSX en cada renderizado -- Escribir onClick={() => handleClick(id)} crea una nueva referencia de función cada renderizado, lo cual puede causar re-renderizados innecesarios en componentes hijos que dependen de igualdad referencial. Solución: Usa useCallback o extrae el manejador a una referencia estable. Para listas, considera un componente hijo que reciba el elemento y adjunte su propio manejador.

• onClick se dispara en CUALQUIER botón del ratón por defecto -- El onClick de React se dispara solo para clics izquierdos en la mayoría de navegadores, pero no se garantiza para todos los elementos y navegadores. Si necesitas distinguir botones, verifica e.button en onMouseDown u onMouseUp.

• Confusión entre e.target y e.currentTarget -- e.target es el elemento que fue realmente hecho clic (podría ser un hijo). e.currentTarget es el elemento al que se adjunta el manejador. Si haces clic en un <span> dentro de un <button>, e.target es el span, e.currentTarget es el button. Acceder a propiedades como .value o .dataset en e.target requiere estrechamiento de tipo.

• onDoubleClick se dispara dos eventos onClick primero -- Un doble clic desencadena: onClick -> onClick -> onDoubleClick. Si tu manejador onClick realiza una acción, obtendrás esa acción dos veces antes de que se dispare el doble clic. Solución: Usa un temporizador de debounce para distinguir clics simples de dobles, o evita combinar ambos en el mismo elemento.

• Los eventos sintéticos se anulan después del manejador -- Acceder a e.clientX dentro de un setTimeout o después de un await devuelve null porque React recicla el objeto de evento. Solución: Lee valores en variables locales antes de cualquier operación asincrónica: const x = e.clientX;.

• -- Adjuntar actualizaciones de estado a puede causar cientos de re-renderizados por segundo. Throttle con o una utilidad de throttle, o usa una ref para almacenar posición y solo re-renderiza cuando sea necesario.

Alternativas

Preguntas Frecuentes

const handleContextMenu = (e: React.MouseEvent<HTMLDivElement>) => {
  e.preventDefault(); // suprime menú predeterminado del navegador
  setMenu({ visible: true, x: e.clientX, y: e.clientY });
};
return <div onContextMenu=

function ItemList({ items }: { items: Item[] }) {
  const handleClick = (item: Item) =>
    (e: React.MouseEvent<HTMLLIElement>) =>

const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
const handleMouseDown = () => {
  timerRef.current = setTimeout(onLongPress, 600);
};
const handleMouseUp

// Tipo de elemento específico
const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
  e.currentTarget; // HTMLButtonElement
};
 
// Fallback genérico para cualquier elemento HTML
const handleAny = (e: React.

const handleDelegated = (e: React.MouseEvent<HTMLUListElement>) => {
  // e.target se tipifica como EventTarget, no Element
  const target = e.target as HTMLElement;
  if (target.tagName === "LI") {
    console.

Relacionado

• Eventos de Teclado -- Respondiendo a pulsaciones de tecla y atajos de teclado
• Eventos de Formulario -- Manejo de envíos de formulario y cambios de entrada

Para mejor desempeño, extrae cada elemento en un componente hijo con su propio manejador estable.