Skip to Content
ComponentsIcignalDropdownMenu

DropdownMenu

트리거 클릭으로 메뉴를 여는 데이터 기반 드롭다운 메뉴 컴포넌트

개요

iCignal DropdownMenu는 Foundation DropdownMenu 계열 컴포넌트를 래핑하여, items 배열 선언만으로 메뉴를 구성할 수 있는 데이터 기반 컴포넌트입니다. 서브컴포넌트를 직접 조합할 필요 없이 아이템 정의만으로 일반 아이템, 그룹, 구분선, 서브메뉴를 표현할 수 있습니다.

주요 특징

  • ✅ 데이터 기반 구성: items 배열로 메뉴 구조 선언
  • ✅ 아이콘/단축키: 아이템에 아이콘과 단축키 텍스트 표시
  • ✅ 그룹/구분선: type: "group", type: "separator"로 메뉴 구조화
  • ✅ 서브메뉴: 아이템의 중첩 items로 다단계 메뉴 지원
  • ✅ 위치 조정: side, align, 오프셋으로 표시 위치 제어
  • ✅ 키보드 접근성: ↑↓ 탐색, Enter 실행, ESC 닫기

사용 예시

기본 사용

trigger에 트리거 요소를, items에 메뉴 아이템 배열을 전달합니다. 트리거를 클릭하면 메뉴가 열립니다.

아이콘과 단축키

아이템에 icon과 shortcut을 추가할 수 있습니다.

그룹과 구분선

type: "group"으로 레이블이 있는 그룹을, type: "separator"로 구분선을 추가합니다.

서브메뉴

일반 아이템에 items를 중첩하면 서브메뉴로 렌더링됩니다.

위치 및 너비 조정

side, align, width로 메뉴의 표시 위치와 너비를 조정합니다.

API Reference

Props (DropdownMenu)

PropTypeDefaultDescription
triggerReactElement-메뉴를 여는 트리거 요소
triggerClassNamestring-트리거 추가 CSS 클래스
itemsDropdownItemProps[]-메뉴 아이템 배열
openboolean-열림 상태 (제어 모드)
widthnumber-메뉴 콘텐츠 너비 (px)
align"start" | "end"-트리거 기준 콘텐츠 정렬
alignOffsetnumber-정렬 방향 오프셋 (px)
side"top" | "right" | "bottom" | "left"-트리거 기준 표시 방향
sideOffsetnumber-표시 방향 오프셋 (px)
classNamestring-콘텐츠 추가 CSS 클래스
PropTypeDefaultDescription
type"group" | "separator"- (일반 아이템)아이템 유형
labelReactNode-아이템 레이블
valuestring-아이템 식별 값
iconReactNode-레이블 좌측 아이콘
shortcutstring-단축키 텍스트
disabledboolean-비활성화 여부
itemsDropdownItemProps[]-서브메뉴/그룹 하위 아이템
classNamestring-아이템 추가 CSS 클래스
labelClassNamestring-레이블 추가 CSS 클래스

Events

EventTypeDescription
onOpenChange(open: boolean) => void열림 상태 변경 콜백
onSelect(item: DropdownItemProps) => void아이템 선택 콜백

기본 사용법

import { DropdownMenu, Button } from "@vortex/ui-icignal"
 
<DropdownMenu
  trigger={<Button variant="outline">메뉴 열기</Button>}
  items={[
    { label: "프로필", value: "profile" },
    { label: "설정", value: "settings" },
    { type: "separator" },
    { label: "로그아웃", value: "logout" },
  ]}
  onSelect={(item) => console.log(item.value)}
/>

접근성

ARIA 속성

Base UI DropdownMenu가 자동으로 제공합니다:

// role="menu", role="menuitem" 자동 적용
// aria-haspopup, aria-expanded 트리거에 자동 적용
<DropdownMenu trigger={<Button>메뉴</Button>} items={items} />

권장 사항

  • ✅ 의미를 알 수 있는 트리거 레이블 제공
  • ✅ 키보드로 ↑↓ 탐색, Enter 실행, ESC 닫기 지원
  • ✅ onSelect에서 item.value로 선택된 항목 식별
  • ❌ 트리거를 아이콘만으로 구성할 경우 aria-label 추가

관련 컴포넌트

Last updated on
DatePickerEditor