Context Menu
Un menú de clic derecho con acciones, atajos y navegación por teclado.
Instalación
Copia y pega el siguiente código en tu proyecto.
1'use client';23import { AnimatePresence, motion, useReducedMotion } from 'motion/react';4import * as React from 'react';5import { cn } from '../lib/cn';6import { useTypeahead } from '../lib/collection';7import { FloatingPortal, useFloating } from '../lib/floating';8import { floatingVariants, reveal } from '../lib/motion';9import { useLayer } from '../lib/overlay';10import { useControllableState } from '../lib/use-controllable-state';1112interface ContextMenuContextValue {13 isOpen: boolean;14 point: { x: number; y: number } | null;15 openAt: (x: number, y: number) => void;16 closeMenu: (options?: { restoreFocus?: boolean }) => void;17 triggerRef: React.RefObject<HTMLDivElement | null>;18 triggerId: string;19 contentId: string;20}2122interface ContextMenuProps {23 children: React.ReactNode;24 className?: string;25 open?: boolean;26 defaultOpen?: boolean;27 onOpenChange?: (open: boolean) => void;28}2930interface ContextMenuTriggerProps extends React.HTMLAttributes<HTMLDivElement> {31 children: React.ReactNode;32 disabled?: boolean;33}3435interface ContextMenuContentProps {36 children: React.ReactNode;37 className?: string;38}3940interface ContextMenuItemProps {41 children: React.ReactNode;42 onClick?: (event: React.MouseEvent<HTMLDivElement>) => void;43 className?: string;44 disabled?: boolean;45 onSelect?: () => void;46 variant?: 'default' | 'destructive';47}4849const CONTEXT_MENU_STYLE = { willChange: 'opacity, transform, filter' } as const;5051const LONG_PRESS_MS = 500;52const LONG_PRESS_TOLERANCE = 10;53const ContextMenuContext = React.createContext<ContextMenuContextValue | null>(null);5455const useContextMenuContext = (): ContextMenuContextValue => {56 const context = React.use(ContextMenuContext);57 if (!context) throw new Error('ContextMenu components must be used within ContextMenu');58 return context;59};6061function getMenuItems(container: HTMLElement | null): HTMLElement[] {62 if (!container) return [];63 return Array.from(64 container.querySelectorAll<HTMLElement>('[role="menuitem"]:not([aria-disabled="true"])'),65 );66}6768const ContextMenuRoot = ({69 children,70 className,71 open,72 defaultOpen = false,73 onOpenChange,74}: ContextMenuProps): React.JSX.Element => {75 const [isOpen, setIsOpen] = useControllableState({76 value: open,77 defaultValue: defaultOpen,78 onChange: onOpenChange,79 });80 const [point, setPoint] = React.useState<{ x: number; y: number } | null>(null);81 const triggerRef = React.useRef<HTMLDivElement>(null);8283 const openAt = React.useCallback(84 (x: number, y: number) => {85 setPoint({ x, y });86 setIsOpen(true);87 },88 [setIsOpen],89 );9091 const closeMenu = React.useCallback(92 (options?: { restoreFocus?: boolean }) => {93 setIsOpen(false);94 if (options?.restoreFocus !== false) {95 triggerRef.current?.focus();96 }97 },98 [setIsOpen],99 );100101 const id = React.useId();102 const triggerId = `context-menu-trigger-${id}`;103 const contentId = `context-menu-content-${id}`;104105 const contextValue = React.useMemo(106 () => ({ isOpen, point, openAt, closeMenu, triggerRef, triggerId, contentId }),107 [isOpen, point, openAt, closeMenu, triggerId, contentId],108 );109110 return (111 <ContextMenuContext value={contextValue}>112 <div className={cn('relative', className)}>{children}</div>113 </ContextMenuContext>114 );115};116117const ContextMenuTrigger = ({118 children,119 className,120 disabled = false,121 onContextMenu,122 onKeyDown,123 ...props124}: ContextMenuTriggerProps): React.JSX.Element => {125 const { isOpen, openAt, triggerRef, triggerId } = useContextMenuContext();126 const longPressTimer = React.useRef<ReturnType<typeof setTimeout> | null>(null);127 const longPressStart = React.useRef<{ x: number; y: number } | null>(null);128129 const clearLongPress = React.useCallback(() => {130 if (longPressTimer.current !== null) {131 clearTimeout(longPressTimer.current);132 longPressTimer.current = null;133 }134 }, []);135136 React.useEffect(() => clearLongPress, [clearLongPress]);137138 const handleContextMenu = React.useCallback(139 (e: React.MouseEvent<HTMLDivElement>) => {140 onContextMenu?.(e);141 if (disabled) return;142 e.preventDefault();143 openAt(e.clientX, e.clientY);144 },145 [disabled, openAt, onContextMenu],146 );147148 const handleTouchStart = React.useCallback(149 (e: React.TouchEvent<HTMLDivElement>) => {150 if (disabled) return;151 const touch = e.touches[0];152 if (!touch) return;153 const { clientX, clientY } = touch;154 clearLongPress();155 longPressStart.current = { x: clientX, y: clientY };156 longPressTimer.current = setTimeout(() => openAt(clientX, clientY), LONG_PRESS_MS);157 },158 [disabled, openAt, clearLongPress],159 );160161 const handleTouchMove = React.useCallback(162 (e: React.TouchEvent<HTMLDivElement>) => {163 const start = longPressStart.current;164 const touch = e.touches[0];165 if (!start || !touch) return;166 const distance = Math.hypot(touch.clientX - start.x, touch.clientY - start.y);167 if (distance > LONG_PRESS_TOLERANCE) clearLongPress();168 },169 [clearLongPress],170 );171172 const handleKeyDown = React.useCallback(173 (e: React.KeyboardEvent<HTMLDivElement>) => {174 onKeyDown?.(e);175 if (disabled) return;176 if ((e.shiftKey && e.key === 'F10') || e.key === 'ContextMenu') {177 e.preventDefault();178 const rect = triggerRef.current?.getBoundingClientRect();179 if (rect) openAt(rect.left + rect.width / 2, rect.top + rect.height / 2);180 }181 },182 [disabled, openAt, triggerRef, onKeyDown],183 );184185 return (186 <div187 ref={triggerRef}188 id={triggerId}189 tabIndex={disabled ? undefined : 0}190 aria-keyshortcuts={disabled ? undefined : 'Shift+F10 ContextMenu'}191 data-state={isOpen ? 'open' : 'closed'}192 onContextMenu={handleContextMenu}193 onTouchStart={handleTouchStart}194 onTouchEnd={clearLongPress}195 onTouchCancel={clearLongPress}196 onTouchMove={handleTouchMove}197 onKeyDown={handleKeyDown}198 className={cn(199 'ring-offset-background focus-visible:ring-ring select-none [-webkit-touch-callout:none] focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none',200 className,201 )}202 {...props}203 >204 {children}205 </div>206 );207};208209const ContextMenuContent = ({210 children,211 className,212}: ContextMenuContentProps): React.JSX.Element | null => {213 const { isOpen, point, closeMenu, triggerRef, contentId, triggerId } = useContextMenuContext();214 const contentRef = React.useRef<HTMLDivElement>(null);215 const layer = useLayer(isOpen, false, contentRef);216 const typeahead = useTypeahead();217 const shouldReduceMotion = useReducedMotion();218 const { style: floatingStyle, side } = useFloating({219 open: isOpen,220 anchorRef: triggerRef,221 floatingRef: contentRef,222 point,223 side: 'bottom',224 align: 'start',225 sideOffset: point ? 0 : 4,226 });227 const verticalSide = side === 'top' ? 'top' : 'bottom';228229 React.useEffect(() => {230 if (!isOpen) return;231 const dismiss = () => closeMenu({ restoreFocus: false });232 const handlePointerDown = (event: PointerEvent) => {233 if (contentRef.current?.contains(event.target as Node)) return;234 if (layer.isInsideUpperLayer(event.target)) return;235 dismiss();236 };237 const handleScroll = (event: Event) => {238 if (event.target instanceof Node && contentRef.current?.contains(event.target)) return;239 dismiss();240 };241 document.addEventListener('pointerdown', handlePointerDown);242 window.addEventListener('scroll', handleScroll, { capture: true, passive: true });243 window.addEventListener('resize', dismiss);244 window.addEventListener('blur', dismiss);245 return () => {246 document.removeEventListener('pointerdown', handlePointerDown);247 window.removeEventListener('scroll', handleScroll, { capture: true });248 window.removeEventListener('resize', dismiss);249 window.removeEventListener('blur', dismiss);250 };251 }, [isOpen, closeMenu, layer]);252253 React.useEffect(() => {254 if (!isOpen) return;255 const frame = requestAnimationFrame(() => {256 getMenuItems(contentRef.current)[0]?.focus({ preventScroll: true });257 });258 return () => cancelAnimationFrame(frame);259 }, [isOpen]);260261 const handleKeyDown = React.useCallback(262 (e: React.KeyboardEvent<HTMLDivElement>) => {263 if (e.key === 'Escape') {264 if (!layer.isTopmost()) return;265 e.preventDefault();266 closeMenu();267 return;268 }269 if (e.key === 'Tab') {270 closeMenu();271 return;272 }273274 const items = getMenuItems(contentRef.current);275 if (items.length === 0) return;276277 const currentIndex = items.indexOf(document.activeElement as HTMLElement);278279 let nextIndex: number | null = null;280 if (e.key === 'ArrowDown') {281 nextIndex = currentIndex < 0 ? 0 : (currentIndex + 1) % items.length;282 } else if (e.key === 'ArrowUp') {283 nextIndex =284 currentIndex < 0 ? items.length - 1 : (currentIndex - 1 + items.length) % items.length;285 } else if (e.key === 'Home') {286 nextIndex = 0;287 } else if (e.key === 'End') {288 nextIndex = items.length - 1;289 } else if (290 e.key.length === 1 &&291 !e.altKey &&292 !e.ctrlKey &&293 !e.metaKey &&294 (e.key !== ' ' || typeahead.isTyping())295 ) {296 e.preventDefault();297 e.stopPropagation();298 typeahead.search(e.key, items, currentIndex)?.focus();299 return;300 }301302 if (nextIndex !== null) {303 e.preventDefault();304 items[nextIndex]?.focus();305 }306 },307 [closeMenu, layer, typeahead],308 );309310 const style = React.useMemo(311 () => ({312 ...floatingStyle,313 ...(isOpen ? null : { visibility: undefined }),314 ...CONTEXT_MENU_STYLE,315 }),316 [floatingStyle, isOpen],317 );318319 return (320 <FloatingPortal>321 <AnimatePresence>322 {isOpen && (323 <motion.div324 ref={contentRef}325 id={contentId}326 role="menu"327 tabIndex={-1}328 aria-labelledby={triggerId}329 onKeyDownCapture={handleKeyDown}330 onContextMenu={(event: React.MouseEvent) => event.preventDefault()}331 variants={shouldReduceMotion ? reveal : floatingVariants[verticalSide]}332 initial="hidden"333 animate="visible"334 exit="exit"335 style={style}336 className={cn(337 'bg-popover text-popover-foreground z-500 max-h-(--available-height) min-w-48 overflow-y-auto overscroll-contain rounded-md shadow-md outline-none',338 verticalSide === 'top' ? 'origin-bottom-left' : 'origin-top-left',339 className,340 )}341 >342 <div className="flex flex-col gap-0.5 p-1">{children}</div>343 </motion.div>344 )}345 </AnimatePresence>346 </FloatingPortal>347 );348};349350const itemClassName = (disabled: boolean, variant: 'default' | 'destructive') =>351 cn(352 'relative flex cursor-pointer items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none select-none',353 'transition-colors duration-150',354 'focus:bg-muted pointer-coarse:py-2.5',355 disabled && 'pointer-events-none opacity-40',356 variant === 'destructive' && 'text-destructive-text focus:text-destructive-text',357 );358359const ContextMenuItem = ({360 children,361 onClick,362 className,363 disabled = false,364 variant = 'default',365 onSelect,366}: ContextMenuItemProps): React.JSX.Element => {367 const { closeMenu } = useContextMenuContext();368369 const handleClick = React.useCallback(370 (e: React.MouseEvent<HTMLDivElement>) => {371 if (disabled) return;372 e.stopPropagation();373 onClick?.(e);374 onSelect?.();375 closeMenu();376 },377 [disabled, onClick, onSelect, closeMenu],378 );379380 const handleKeyDown = React.useCallback(381 (e: React.KeyboardEvent<HTMLDivElement>) => {382 if (disabled) return;383 if (e.key === 'Enter' || e.key === ' ') {384 e.preventDefault();385 e.stopPropagation();386 onClick?.(e as unknown as React.MouseEvent<HTMLDivElement>);387 onSelect?.();388 closeMenu();389 }390 },391 [disabled, onClick, onSelect, closeMenu],392 );393394 const handlePointerMove = React.useCallback(395 (e: React.PointerEvent<HTMLDivElement>) => {396 if (disabled || e.pointerType === 'touch') return;397 if (document.activeElement !== e.currentTarget) e.currentTarget.focus();398 },399 [disabled],400 );401402 const handlePointerLeave = React.useCallback((e: React.PointerEvent<HTMLDivElement>) => {403 if (document.activeElement !== e.currentTarget) return;404 e.currentTarget.closest<HTMLElement>('[role="menu"]')?.focus();405 }, []);406407 return (408 <div409 role="menuitem"410 tabIndex={-1}411 aria-disabled={disabled || undefined}412 onClick={handleClick}413 onKeyDown={handleKeyDown}414 onPointerMove={handlePointerMove}415 onPointerLeave={handlePointerLeave}416 className={cn(itemClassName(disabled, variant), className)}417 >418 {children}419 </div>420 );421};422423const ContextMenuLabel = ({424 children,425 className,426}: {427 children: React.ReactNode;428 className?: string;429}) => {430 return (431 <div432 role="presentation"433 className={cn('text-muted-foreground px-2 py-2 text-xs font-medium', className)}434 >435 {children}436 </div>437 );438};439440const ContextMenuSeparator = ({ className }: { className?: string }) => {441 return (442 <div443 role="separator"444 aria-orientation="horizontal"445 className={cn('bg-border/50 my-1 h-px', className)}446 />447 );448};449450const ContextMenuShortcut = ({451 children,452 className,453}: {454 children: React.ReactNode;455 className?: string;456}) => {457 return (458 <span className={cn('text-muted-foreground ms-auto ps-6 text-xs tracking-widest', className)}>459 {children}460 </span>461 );462};463464const ContextMenu = Object.assign(ContextMenuRoot, {465 Trigger: ContextMenuTrigger,466 Content: ContextMenuContent,467 Item: ContextMenuItem,468 Label: ContextMenuLabel,469 Separator: ContextMenuSeparator,470 Shortcut: ContextMenuShortcut,471});472473export { ContextMenu };474export type {475 ContextMenuContentProps,476 ContextMenuItemProps,477 ContextMenuProps,478 ContextMenuTriggerProps,479};
Actualiza las rutas de importación para que coincidan con la estructura de tu proyecto.
Anatomía
1import { ContextMenu } from '@/components/context-menu';
1<ContextMenu>2 <ContextMenu.Trigger>Haz clic derecho aquí</ContextMenu.Trigger>3 <ContextMenu.Content>4 <ContextMenu.Label>Acciones</ContextMenu.Label>5 <ContextMenu.Separator />6 <ContextMenu.Item>7 Copiar8 <ContextMenu.Shortcut>Ctrl C</ContextMenu.Shortcut>9 </ContextMenu.Item>10 <ContextMenu.Item variant="destructive">Eliminar</ContextMenu.Item>11 </ContextMenu.Content>12</ContextMenu>
El menú se abre en el puntero con clic derecho, con pulsación larga en pantallas táctiles, y desde el teclado con Shift F10 o la tecla de menú contextual. Se renderiza en un portal, así que un padre con
overflow: hidden nunca lo recorta, se mantiene dentro del viewport y se cierra cuando la página hace scroll o la ventana pierde el foco. Las flechas, Home, End y Escape funcionan como en cualquier menú, y escribir las primeras letras de un item lo enfoca.Composición
Usa la siguiente composición para construir un
ContextMenu:ContextMenu├── ContextMenu.Trigger└── ContextMenu.Content├── ContextMenu.Label├── ContextMenu.Item│ └── ContextMenu.Shortcut└── ContextMenu.Separator
Referencia de API
ContextMenu
| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | - | Estado abierto controlado |
defaultOpen | boolean | false | Estado abierto inicial cuando no está controlado |
onOpenChange | (open: boolean) => void | - | Callback cuando cambia el estado abierto |
className | string | - | Clases CSS adicionales |
ContextMenu.Trigger
| Prop | Type | Default | Description |
|---|---|---|---|
disabled | boolean | false | Ignora el clic derecho y la pulsación larga |
className | string | - | Clases CSS adicionales |
ContextMenu.Item
| Prop | Type | Default | Description |
|---|---|---|---|
disabled | boolean | false | Deshabilita el elemento |
variant | 'default' | 'destructive' | 'default' | Estilo visual |
onSelect | () => void | - | Callback al seleccionar |
className | string | - | Clases CSS adicionales |
ContextMenu.Label
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | - | Texto de etiqueta |
ContextMenu.Shortcut
Pista alineada a la derecha dentro de un elemento. Es solo visual, no registra el atajo.
ContextMenu.Separator
Separador visual entre elementos del menú. Sin props.
¿Encontraste algo que mejorar?
¿Notaste un error, tipografía o detalle faltante en esta página? Ayúdanos a mejorar la documentación abriendo un issue en GitHub.