DropdownMenu

트리거를 누르면 동작 목록이 열려요. 버튼으로 모두 배치하기에는 동작이 많을 때 써요. 값 하나를 골라 둘 때는 Select를 써요.

사용 예시

동작 목록

화살표 키로 항목 사이를 이동하고 Esc로 닫아요.

마지막 동작: 없음

tsx

<DropdownMenu>  <DropdownMenuTrigger render={<Button color="neutral" emphasis="outline" />}>    더 보기    <ChevronDown />  </DropdownMenuTrigger>  <DropdownMenuContent>    <DropdownMenuItem lead={<Pencil />} onClick={renameItem}>이름 바꾸기</DropdownMenuItem>    <DropdownMenuItem lead={<Copy />} onClick={duplicateItem}>복제</DropdownMenuItem>    <DropdownMenuItem lead={<Archive />} onClick={archiveItem}>보관함으로 옮기기</DropdownMenuItem>  </DropdownMenuContent></DropdownMenu>

권장

Select는 고른 값이 트리거에 계속 보여요.

지양

DropdownMenu는 메뉴가 닫히면 고른 값을 트리거에서 볼 수 없어요.

체크 항목

여러 항목을 함께 체크할 때 써요. 눌러도 메뉴가 닫히지 않아서 연달아 체크할 수 있어요.

만든 사람 보임, 수정한 날짜 숨김

tsx

<DropdownMenu>  <DropdownMenuTrigger render={<Button color="neutral" emphasis="outline" />}>    보일 열    <ChevronDown />  </DropdownMenuTrigger>  <DropdownMenuContent>    <DropdownMenuCheckboxItem checked={showAuthor} onCheckedChange={setShowAuthor}>만든 사람</DropdownMenuCheckboxItem>    <DropdownMenuCheckboxItem checked={showUpdated} onCheckedChange={setShowUpdated}>수정한 날짜</DropdownMenuCheckboxItem>  </DropdownMenuContent></DropdownMenu>

권장

체크 표시로 상태를 보여요.

지양

항목 이름에 상태를 적으면 지금 상태로도, 누르면 실행할 동작으로도 읽혀요.

보기 메뉴

정렬 기준처럼 바로 적용되는 보기 설정을 체크 항목과 한 메뉴에 둘 때 써요.

최근 수정순, 폴더 먼저 보기 체크

tsx

<DropdownMenu>  <DropdownMenuTrigger render={<Button color="neutral" emphasis="outline" />}>    보기    <ChevronDown />  </DropdownMenuTrigger>  <DropdownMenuContent>    <DropdownMenuGroup label="정렬">      <DropdownMenuRadioGroup value={sort} onValueChange={setSort}>        <DropdownMenuRadioItem value="name">이름순</DropdownMenuRadioItem>        <DropdownMenuRadioItem value="updated">최근 수정순</DropdownMenuRadioItem>        <DropdownMenuRadioItem value="created">만든 날짜순</DropdownMenuRadioItem>      </DropdownMenuRadioGroup>    </DropdownMenuGroup>    <DropdownMenuSeparator />    <DropdownMenuCheckboxItem checked={foldersFirst} onCheckedChange={setFoldersFirst}>폴더 먼저 보기</DropdownMenuCheckboxItem>  </DropdownMenuContent></DropdownMenu>

그룹과 구분선

항목이 종류별로 나뉠 때 써요. 자주 쓰는 항목에는 단축키를 함께 보여요.

tsx

<DropdownMenu>  <DropdownMenuTrigger render={<Button color="neutral" emphasis="outline" />}>    더 보기    <ChevronDown />  </DropdownMenuTrigger>  <DropdownMenuContent className="min-w-56">    <DropdownMenuGroup label="이 항목">      <DropdownMenuItem lead={<Pencil />} trail={<Kbd>F2</Kbd>}>이름 바꾸기</DropdownMenuItem>      <DropdownMenuItem lead={<Copy />} trail={<><Kbd>Ctrl</Kbd><Kbd>D</Kbd></>}>복제</DropdownMenuItem>    </DropdownMenuGroup>    <DropdownMenuSeparator />    <DropdownMenuGroup label="목록">      <DropdownMenuItem lead={<Settings />}>기본값 바꾸기</DropdownMenuItem>    </DropdownMenuGroup>  </DropdownMenuContent></DropdownMenu>

하위 메뉴

같은 동작이 여러 종류로 나뉠 때 써요. DropdownMenuSubTrigger에서 오른쪽 화살표 키를 눌러도 열려요.

tsx

<DropdownMenu>  <DropdownMenuTrigger render={<Button color="neutral" emphasis="outline" />}>    더 보기    <ChevronDown />  </DropdownMenuTrigger>  <DropdownMenuContent>    <DropdownMenuItem lead={<Pencil />}>이름 바꾸기</DropdownMenuItem>    <DropdownMenuSub>      <DropdownMenuSubTrigger>옮기기</DropdownMenuSubTrigger>      <DropdownMenuSubContent>        <DropdownMenuItem>진행 중</DropdownMenuItem>        <DropdownMenuItem>보관함</DropdownMenuItem>        <DropdownMenuItem>지난 자료</DropdownMenuItem>      </DropdownMenuSubContent>    </DropdownMenuSub>  </DropdownMenuContent></DropdownMenu>

권장

하위 메뉴는 한 단계만 둬요.

지양

두 단계로 열면 원하는 항목까지 마우스를 옮기는 거리가 길어져요. 종류가 그만큼 많으면 Dialog를 써요.

되돌릴 수 없는 항목

지우기처럼 되돌릴 수 없는 항목에만 danger를 써요. 맨 아래에 두고 구분선으로 나눠서 잘못 누르지 않게 해요.

tsx

<DropdownMenu>  <DropdownMenuTrigger render={<Button color="neutral" emphasis="outline" />}>    관리    <ChevronDown />  </DropdownMenuTrigger>  <DropdownMenuContent>    <DropdownMenuItem lead={<Pencil />}>이름 바꾸기</DropdownMenuItem>    <DropdownMenuSeparator />    <DropdownMenuItem color="danger" lead={<Trash2 />}>지우기</DropdownMenuItem>  </DropdownMenuContent></DropdownMenu>

오른쪽 끝 정렬

트리거가 오른쪽 끝에 있으면 align을 end로 둬요.

여름 캠페인

tsx

<DropdownMenu>  <DropdownMenuTrigger render={<Button color="neutral" emphasis="ghost" shape="square" aria-label="더 보기" />}>    <Ellipsis />  </DropdownMenuTrigger>  <DropdownMenuContent align="end">    <DropdownMenuItem>복제</DropdownMenuItem>    <DropdownMenuItem>보관함으로 옮기기</DropdownMenuItem>  </DropdownMenuContent></DropdownMenu>

위로 여는 메뉴

화면 아래에 붙은 도구 모음처럼 트리거 아래에 자리가 없으면 side를 top으로 둬요.

3개 고름

tsx

<DropdownMenu>  <DropdownMenuTrigger render={<Button color="neutral" emphasis="outline" />}>    옮기기    <ChevronDown />  </DropdownMenuTrigger>  <DropdownMenuContent side="top" align="end">    <DropdownMenuItem>진행 중</DropdownMenuItem>    <DropdownMenuItem>보관함</DropdownMenuItem>    <DropdownMenuItem>지난 자료</DropdownMenuItem>  </DropdownMenuContent></DropdownMenu>

항목 설명

권한처럼 이름만으로 차이를 알기 어려우면 DropdownMenuItemDescription으로 한 줄 설명을 더해요. 항목 높이가 내용만큼 늘고, 점과 lead는 첫 줄에 맞춰요.

tsx

<DropdownMenuRadioGroup value={role} onValueChange={setRole}>  <DropdownMenuRadioItem value="manager">    관리자    <DropdownMenuItemDescription>업무를 승인하고 구성원을 초대해요.</DropdownMenuItemDescription>  </DropdownMenuRadioItem>  …</DropdownMenuRadioGroup>

컨트롤

side

align

color

arrow

disabled

tsx

<DropdownMenu>  <DropdownMenuTrigger render={<Button color="neutral" emphasis="outline" />}>더 보기</DropdownMenuTrigger>  <DropdownMenuContent>    <DropdownMenuItem>복제</DropdownMenuItem>    <DropdownMenuSeparator />    <DropdownMenuItem>지우기</DropdownMenuItem>  </DropdownMenuContent></DropdownMenu>

명세

이름
이름	값	기본
DropdownMenu
open	boolean	-
호출하는 쪽에서 열림 상태를 관리해요.
defaultOpen	boolean	false
처음에 열어 둘지 정해요.
onOpenChange	(open: boolean, eventDetails) => void	-
열리거나 닫히면 호출돼요.
render	ReactElement	-
기본 요소 대신 그릴 요소예요. DropdownMenuTrigger에 Button을 넘길 때 써요.
className	string	-
DropdownMenuSub를 뺀 모든 하위 컴포넌트에 쓸 수 있어요.
DropdownMenuContent
side	top, right, bottom, left	bottom
트리거를 기준으로 메뉴가 열리는 쪽이에요. 화면에 자리가 없으면 반대쪽에 열려요.
align	start, center, end	start
트리거를 기준으로 메뉴를 정렬하는 위치예요.
arrow	boolean	true
트리거를 가리키는 화살표예요.
anchor	Element, ref, 가상 요소, 함수	-
트리거 대신 기준으로 삼을 곳이에요. getBoundingClientRect를 가진 객체를 넘기면 화면 좌표 사각형을 기준으로 열어요.
sideOffset	number, 함수	14, arrow가 없으면 8
기준과 떨어진 거리예요. 단위는 px이에요.
alignOffset	number, 함수	0
align 방향으로 옮기는 거리예요. 단위는 px이에요.
collisionAvoidance	object	-
화면 가장자리에 닿을 때 뒤집을지, 밀어 넣을지 정해요. Base UI Positioner의 값을 그대로 받아요.
DropdownMenuItem
color	neutral, danger	neutral
danger면 글자색과 강조됐을 때의 배경색이 바뀌어요.
lead	ReactNode	-
항목 앞에 보여요. 아이콘 크기는 16px로 정해져 있어요.
trail	ReactNode	-
항목 오른쪽 끝에 보여요.
disabled	boolean	false
closeOnClick	boolean	true
false면 누른 뒤에도 메뉴가 열려 있어요.
onClick	(event) => void	-
항목을 누르면 호출돼요.
DropdownMenuItemDescription
children	ReactNode	-
항목 이름 아래 짧은 설명이에요. Item, CheckboxItem, RadioItem, SubTrigger 안에 두고, 항목의 aria-describedby로 이어져요.
className	string	-
DropdownMenuCheckboxItem
checked	boolean	-
호출하는 쪽에서 체크 상태를 관리해요.
onCheckedChange	(checked: boolean, eventDetails) => void	-
체크 상태가 바뀌면 호출돼요.
disabled	boolean	false
DropdownMenuGroup
label	string	-
그룹 위에 보이는 제목이에요.
DropdownMenuRadioGroup
value	string	-
호출하는 쪽에서 고른 항목을 관리해요.
onValueChange	(value: string, eventDetails) => void	-
고른 항목이 바뀌면 호출돼요.
DropdownMenuRadioItem
value	string	필수
DropdownMenuRadioGroup의 value와 같으면 항목 앞에 점이 보여요.
disabled	boolean	false
DropdownMenuSub
open	boolean	-
호출하는 쪽에서 열림 상태를 관리해요.
defaultOpen	boolean	false
처음에 열어 둘지 정해요.
onOpenChange	(open: boolean, eventDetails) => void	-
열리거나 닫히면 호출돼요.
DropdownMenuSubTrigger
disabled	boolean	false