Skip to Content
ComponentsIcignalContextMenu

ContextMenu

요소 우클릭 시 상황별 메뉴를 표시하는 컴포넌트

개요

iCignal ContextMenu는 Foundation ContextMenu(Base UI Menu 기반)를 래핑하여 메뉴 항목을 items 배열 데이터로 선언적으로 구성할 수 있도록 한 컴포넌트입니다. 일반 항목, 체크박스, 라디오 그룹, 서브메뉴, 구분선을 지원하며, trigger로 지정한 영역을 우클릭하면 메뉴가 열립니다.

주요 특징

  • ✅ 데이터 기반 구성: items 배열만으로 메뉴 렌더링
  • ✅ 다양한 항목 타입: 일반, checkbox, radio-group, separator 지원
  • ✅ 서브메뉴: items 중첩으로 다단계 메뉴 구성
  • ✅ 단축키 표시: 항목별 shortcut 텍스트 표시
  • ✅ 위험 항목: variant=“destructive”로 위험 작업 강조
  • ✅ 너비 지정: width prop으로 메뉴 너비 고정 가능

사용 예시

기본 사용법

trigger로 지정한 영역을 우클릭하면 메뉴가 열립니다.

여기를 우클릭하세요

체크박스와 라디오 그룹

checkbox 타입으로 토글 옵션을, radio-group 타입으로 단일 선택 옵션을 제공합니다.

보기 옵션 — 우클릭

서브메뉴와 위험 항목

항목에 items를 중첩하면 서브메뉴가 되고, variant=“destructive”로 위험 작업을 강조합니다.

파일 옵션 — 우클릭

API Reference

Props

PropTypeDefaultDescription
triggerReactNode(필수)우클릭으로 메뉴를 여는 영역
itemsContextItemProps[](필수)메뉴 항목 배열
widthnumber-메뉴 너비 (px)

ContextItemProps

PropTypeDefaultDescription
type"separator" | "radio-group" | "checkbox"-항목 타입 (미지정 시 일반/서브메뉴 항목)
labelstring-항목 텍스트 (radio-group 타입은 그룹 레이블)
valuestring-항목 식별 값
shortcutstring-항목 우측 단축키 표시
disabledboolean-비활성화 여부
insetboolean-좌측 들여쓰기 여부
checkedboolean-checkbox 타입의 체크 상태
selectedValuestring-radio-group 타입의 현재 선택 값
variant"default" | "destructive""default"항목 스타일
itemsContextItemProps[]-서브메뉴 또는 radio-group 하위 항목 목록

Events

EventTypeDescription
onSelect(item: ContextItemProps) => void항목 선택 콜백
onOpenChange(open: boolean) => void메뉴 열림 상태 변경 콜백

기본 사용법

import { ContextMenu } from "@vortex/ui-icignal"
 
<ContextMenu
  trigger={<div>우클릭 영역</div>}
  width={220}
  items={[
    { label: "이름 바꾸기", value: "rename" },
    { type: "checkbox", label: "고정", value: "pin", checked: true },
    { type: "separator" },
    { label: "삭제", value: "delete", variant: "destructive" },
  ]}
  onSelect={(item) => console.log(item.value)}
/>

접근성

ARIA 속성

Base UI Menu 기반 Foundation ContextMenu가 자동으로 제공합니다:

  • role="menu" 및 항목별 role="menuitem", role="menuitemcheckbox", role="menuitemradio" 적용
  • 체크/라디오 항목에 aria-checked 자동 적용
  • 키보드 ↑/↓로 항목 탐색, →/←로 서브메뉴 진입·복귀, ESC로 닫기
  • 메뉴가 열리면 포커스가 메뉴로 이동하고 닫히면 트리거로 복귀

권장 사항

  • ✅ 파괴적 작업에는 variant="destructive" 사용
  • ✅ 긴 메뉴는 separator와 서브메뉴로 구조화
  • ❌ 우클릭 메뉴에만 기능을 숨기지 말고, 일반 버튼 등 대체 진입점 제공

관련 컴포넌트

Last updated on
CommandDataTable