Skip to Content
ComponentsCalsContextMenu

ContextMenu

좌표로 여는 컨텍스트 메뉴 컴포넌트입니다.


개요

CALS ContextMenu는 Foundation ContextMenu를 래핑합니다. shadcn처럼 트리거를 감싸지 않고, 소비자가 여는 이벤트를 받아 open·x·y로 넘깁니다.

주요 특징

  • ✅ 좌표로 열기: x·y는 뷰포트 좌표(clientX·clientY)
  • ✅ 여는 이벤트는 소비자 몫: 우클릭·ContextMenu 키·Shift+F10이 모두 contextmenu 이벤트
  • ✅ 항목 배열: items로 항목·구분선·비활성·숨김·destructive를 정한다
  • ✅ 위치 조정: side·align·sideOffset·alignOffset

기본 사용

대상의 onContextMenu에서 기본 메뉴를 막고 좌표와 열림 상태를 넘깁니다.

우클릭하세요

선택: 없음


항목 상태 (disabled / hidden / destructive)

disabled는 누를 수 없고, hidden은 그리지 않으며, type: "destructive"는 위험 동작 색으로 그립니다.

우클릭 - disabled/hidden/destructive

항목 클릭 후 닫기 (hideOnClick)

기본(true)은 항목을 누르면 닫힙니다. false면 눌러도 열린 채로 둡니다.

우클릭 - 기본(닫힘)
우클릭 - hideOnClick={false}

위치 (side / align / sideOffset / alignOffset)

좌표(x·y)를 기준으로 펼칠 방향과 간격을 정합니다. 기본은 bottom·start·0·0입니다.

우클릭 - 기본
우클릭 - side=right align=center sideOffset=8

팝업 꾸밈 (className / style)

className·style은 메뉴 팝업(role="menu")에 붙습니다.

우클릭 - className·style

메뉴 이름 (aria-label)

aria-label(또는 aria-labelledby)이 메뉴 이름이 됩니다.

우클릭 - aria-label=탭 메뉴

키보드로 열기

대상에 tabIndex를 주면 onContextMenu 하나로 우클릭·ContextMenu 키·Shift+F10이 모두 열립니다. 키보드로 열면 좌표가 없어 요소 위치로 계산합니다.

Tab으로 들어와 ContextMenu 키 또는 Shift+F10

API Reference

Props

Prop타입기본값설명
openboolean-열림/닫힘 상태
onOpenChange(open: boolean) => void-상태 변경 콜백
xnumber0메뉴 X 좌표
ynumber0메뉴 Y 좌표
position"fixed" | "absolute""fixed"CSS position 전략
itemsContextMenuItem[][]메뉴 항목 목록
onItemClick(item: ContextMenuItem) => void-항목 클릭 콜백
hideOnClickbooleantrue클릭 후 자동 닫힘
side"top" | "bottom" | "left" | "right" | …"bottom"좌표 기준 펼침 방향
align"start" | "center" | "end""start"정렬
sideOffsetnumber0방향 쪽 간격(px)
alignOffsetnumber0정렬 쪽 간격(px)
aria-label / aria-labelledbystring-메뉴 이름
classNamestring-메뉴 팝업 className
styleCSSProperties-메뉴 팝업 인라인 스타일 (className과 같은 요소)

ContextMenuItem

Prop타입기본값설명
keystring-고유 키
labelstring-표시 텍스트
type"default" | "destructive" | "separator""default"항목 유형
hiddenbooleanfalse숨김 여부
disabledbooleanfalse비활성화 여부

접근성

  • role="menu", 각 항목 role="menuitem"
  • 키보드 탐색: ArrowUp/Down, Enter
  • Escape 키 또는 외부 클릭으로 닫히고, 닫으면 열기 전 요소로 포커스가 돌아온다

권장 사항

  • ✅ 키보드로도 열 수 있게 대상에 tabIndex를 주고 onContextMenu 하나로 받는다
  • ✅ 메뉴 이름이 필요하면 aria-label(또는 aria-labelledby)을 준다
  • ❌ 메뉴에만 있는 기능을 두지 않는다 (우클릭을 모르는 사용자도 쓸 수 있는 다른 경로를 둔다)

관련 컴포넌트

  • DropdownMenu: 트리거를 감싸는 메뉴가 필요할 때
  • TagView: 탭 우클릭 메뉴를 내장한 컴포넌트
Last updated on