Command

Open

Dialog

󰕈

Inline

Small

󰕋

Medium

󰕈

Large

󰕇

Sizes

계약

Overview

Machine-readable contract from Component Spec.

component: commandexport: Commandversion: 1attributes: data-refineui=command

Anatomy

Part	data-refineui
root	command
empty	command-empty
group	command-group
group_heading	command-group-heading
indicator	command-indicator
input	command-input
item	command-item
list	command-list
separator	command-separator
shortcut	command-shortcut

Variants

Axis	Values
size	sm, md, lg

States

Scope	Category	Values
component	pseudo	focus-visible
component	component	data-state: disabled, active, default
component	environment	forced-colors, dir

Accessibility

Slot	Element	Role	Required attributes
command-item	div	option	aria-selected: required=true, type: boolean

Keyboard

Key	Action	Native
ArrowDown	next-trigger	—
ArrowUp	previous-trigger	—
Home	first-trigger	—
End	last-trigger	—
Enter	activate	—

Focus

Section	Property	Value
visual	required	true
visual	selector	:focus-visible

Layout

Property	Value
direction	logical
rtl	true

설치

npmyarnpnpmbun

npm install @refineui/react @refineui/tokens

사용법

import {
  Command,
  CommandInput,
  CommandList,
  CommandEmpty,
  CommandGroup,
  CommandGroupHeading,
  CommandItem,
  CommandSeparator
} from "@refineui/react";

<Command>
  <CommandInput placeholder="Search commands..." />
  <CommandList>
    <CommandEmpty>No results found.</CommandEmpty>
    <CommandGroup>
      <CommandGroupHeading>File</CommandGroupHeading>
      <CommandItem value="new" onSelect={() => handleNew()}>
        New File
      </CommandItem>
      <CommandItem value="open">Open</CommandItem>
    </CommandGroup>
    <CommandSeparator />
    <CommandGroup>
      <CommandGroupHeading>Edit</CommandGroupHeading>
      <CommandItem value="copy">Copy</CommandItem>
      <CommandItem value="paste">Paste</CommandItem>
    </CommandGroup>
  </CommandList>
</Command>

<CommandDialog open={isOpen} onOpenChange={setIsOpen}>
  <CommandInput placeholder="Search commands..." />
  <CommandList>{/* 위와 같은 그룹과 항목 */}</CommandList>
</CommandDialog>

API 레퍼런스

Command

Prop	Default	Type	Description
size	"md"	"sm" | "md" | "lg"	검색 필드, 결과 패널 반경, 항목 행의 밀도 — SearchField와 같은 단계.
value	—	string	제어형 검색 쿼리.
defaultValue	—	string	비제어형 초기 검색 쿼리.
onValueChange	—	(search: string) => void	검색 변경 시 이벤트 핸들러.
shouldFilter	true	boolean	true이면 검색 텍스트로 항목을 필터링합니다.
filter	—	CommandFilter	커스텀 점수 함수(0을 반환하면 숨김).
selectedValue	—	string	제어형 하이라이트 항목 값.
defaultSelectedValue	—	string	비제어형 초기 하이라이트 항목.
onSelectedValueChange	—	(value: string) => void	하이라이트 항목 변경 시 이벤트 핸들러.
label	—	string	접근 가능한 이름(`aria-label`).

CommandDialog

Dialog 오버레이 안의 Command.

Prop	Default	Type	Description
open	—	boolean	제어형 열림 상태.
onOpenChange	—	(open: boolean) => void	열림 상태 변경 시 이벤트 핸들러.
commandProps	—	CommandProps	내부 Command로 전달되는 props. 여기서 Command 크기 기본값은 "lg"이며, CommandDialog 자체의 `size`는 다이얼로그 너비입니다.

CommandInput

선택적 startIcon이 있는 검색 입력.

CommandList

결과 수에 맞춰 최대 높이까지 늘어나고, 넘치면 스크롤되는 리스트 컨테이너(내부적으로 ScrollArea 사용). 선택 항목으로 하이라이트 하나가 미끄러지듯 이동하고, 검색 결과가 바뀌면 높이가 부드럽게 변합니다. 둘 다 prefers-reduced-motion을 따릅니다.

CommandEmpty

일치하는 항목이 없을 때 표시.

CommandGroup

관련 항목을 그룹화합니다.

CommandGroupHeading

그룹 제목.

CommandSeparator

시각적 구분선.

CommandItem

Prop	Default	Type	Description
value	—	string	필터링·선택용 고유 값(필수).
keywords	—	string[]	기본 필터용 추가 문자열.
onSelect	—	(value: string) => void	활성화 시 호출(클릭/Enter).
forceMount	false	boolean	필터로 제외되어도 마운트 유지.
startIcon	—	ReactNode	앞쪽 아이콘.
endIcon	—	ReactNode	뒤쪽 아이콘.
shortcut	—	ReactNode	키보드 단축키 힌트.