💡

Command

Created

2026/01/22 10:40

Context

Auto-complete 컴포넌트를 만들기 위해 검색 기능을 탑재한 Popover가 필요했다. shadcn에서는 Command라는 컴포넌트를 활용하여 기능을 구현한다. 이 컴포넌트를 분석하고 이해하기 위해 이 글을 작성한다.

Agenda

•

Command컴포넌트를 분석하고 이해하는 것을 목표로 함

Auto-complete 컴포넌트는 사용자가 입력하는 것을 기반으로 옵션에서 찾고 선택 시 그 값을 할당한다. 일반적으로 Auto-complete는 Input 형태로 사용자가 직접 입력할 수 있어야하는데, 이 경우 몇몇 문제가 있다. 사용자의 요구사항이 발생한적이 있었는데, 어느 값을 입력한 뒤 선택 후 다시 재입력 할 때 이 때 새로운 값을 선택하지 않으면 이전 값으로 남아있게 해달라는 것이었다. 상태 값을 저장해두는 것으로 큰 어려움이 있지는 않지만 통일성이 깨지는 느낌이다. shadcn에서 레퍼런스를 찾던 중 Command라는 컴포넌트가 있어 이 것에 대해 분석해본다.

Command

const Command = ({
	className,
	...props
}: React.ComponentProps<typeof CommandPrimitive>) => {
	return (
		<CommandPrimitive
			data-slot='command'
			className={cn(
				'bg-popover text-popover-foreground flex h-full w-full flex-col overflow-hidden rounded-md',
				className,
			)}
			{...props}
		/>
	);
};
TypeScript
복사

Command 컴포넌트이다. 다른 shadcn/ui 컴포넌트와 같게 어느 컴포넌트를 감싸는 Wrapper 형식으로 간단하게 구현되어 있다. 그런데, 이 Command는 radix-ui가 아닌 cmdk라는 라이브러리의 컴포넌트이다. 기본 스타일링으로 flex display에 그 안의 항목들을 세로로 배치한다. 이 Command 컴포넌트는 아래서 기술할 여러 컴포넌트를 감싸는 또다른 Wrapper이다.

CommandDialog

const CommandDialog = ({
	title = 'Command Palette',
	description = 'Search for a command to run...',
	children,
	className,
	showCloseButton = true,
	...props
}: React.ComponentProps<typeof Dialog> & {
	title?: string;
	description?: string;
	className?: string;
	showCloseButton?: boolean;
}) => {
	return (
		<Dialog {...props}>
			<DialogHeader className='sr-only'>
				<DialogTitle>{title}</DialogTitle>
				<DialogDescription>{description}</DialogDescription>
			</DialogHeader>
			<DialogContent
				className={cn('overflow-hidden p-0', className)}
				showCloseButton={showCloseButton}
			>
				<Command className='**:[[cmdk-group-heading]]:text-muted-foreground **:data-[slot=command-input-wrapper]:h-12 **:[[cmdk-group-heading]]:px-2 **:[[cmdk-group-heading]]:font-medium **:[[cmdk-group]]:px-2 [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 **:[[cmdk-input]]:h-12 **:[[cmdk-item]]:px-2 **:[[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5'>
					{children}
				</Command>
			</DialogContent>
		</Dialog>
	);
};
TypeScript
복사

Command에 렌더링 될 항목을 감싸는 컴포넌트이다. shadcn/ui의 Dialog 컴포넌트를 활용하여 템플릿을 구성한다.

CommandInput

const CommandInput = ({
	className,
	...props
}: React.ComponentProps<typeof CommandPrimitive.Input>) => {
	return (
		<div
			data-slot='command-input-wrapper'
			className='flex h-10 items-center gap-2 border-b px-3'
		>
			<SearchIcon className='size-4 shrink-0 opacity-50' />
			<CommandPrimitive.Input
				data-slot='command-input'
				className={cn(
					'placeholder:text-muted-foreground flex h-10 w-full rounded-md bg-transparent py-3 text-sm outline-hidden disabled:cursor-not-allowed disabled:opacity-50',
					className,
				)}
				{...props}
			/>
		</div>
	);
};
TypeScript
복사

CommandInput 컴포넌트는 Command 안에서 사용되는 검색 입력 컴포넌트이다. 보통 이 아래에 CommandList가 배치 되며 입력한 것을 기반으로 CommandList가 필터링 되어 표시 된다.

원래 CommandInput 내부의 wrapper인 div의 className은 다음과 같았다.

className='flex h-9 items-center gap-2 border-b px-3'
JavaScript
복사

그런데 CommandPrimitive.Input의 height이 h-10으로 되어있어서 h-10으로 수정하였다.

CommandList

const CommandList = ({
	className,
	...props
}: React.ComponentProps<typeof CommandPrimitive.List>) => {
	return (
		<CommandPrimitive.List
			data-slot='command-list'
			className={cn(
				'max-h-75 scroll-py-1 overflow-x-hidden overflow-y-auto',
				className,
			)}
			{...props}
		/>
	);
};
TypeScript
복사

Command 항목이 표시 되는 영역이다. CommandItem이 표시되는 곳이다.

CommandEmpty

const CommandEmpty = ({
	...props
}: React.ComponentProps<typeof CommandPrimitive.Empty>) => {
	return (
		<CommandPrimitive.Empty
			data-slot='command-empty'
			className='py-6 text-center text-sm'
			{...props}
		/>
	);
};
TypeScript
복사

CommandList에 대상이 없을 때 노출 되는 항목이다.

CommandGroup

const CommandGroup = ({
	className,
	...props
}: React.ComponentProps<typeof CommandPrimitive.Group>) => {
	return (
		<CommandPrimitive.Group
			data-slot='command-group'
			className={cn(
				'text-foreground **:[[cmdk-group-heading]]:text-muted-foreground overflow-hidden p-1 **:[[cmdk-group-heading]]:px-2 **:[[cmdk-group-heading]]:py-1.5 **:[[cmdk-group-heading]]:text-xs **:[[cmdk-group-heading]]:font-medium',
				className,
			)}
			{...props}
		/>
	);
};
TypeScript
복사

Command에 표시 되는 List는 Group을 지어서 표시 될 수 있다. 이 Group 단위의 Wrapper를 담당하는 CommandGroup 컴포넌트이다. CommandGroup의 heading 파라미터에 값을 부여해서 해당 그룹의 타이틀을 표시할 수 있다.

CommandSeparator

const CommandSeparator = ({
	className,
	...props
}: React.ComponentProps<typeof CommandPrimitive.Separator>) => {
	return (
		<CommandPrimitive.Separator
			data-slot='command-separator'
			className={cn('bg-border -mx-1 h-px', className)}
			{...props}
		/>
	);
};
TypeScript
복사

그룹과 그룹간 분리선을 표시 해주는 컴포넌트이다. -mx-1은 양쪽으로 이 분리선을 늘려주는 역할을 수행하는데 왜냐하면 만약 부모 컴포넌트에 패딩이 있으면 분리선이 끝까지 가지 않기 때문이다.

CommandItem

const CommandItem = ({
	className,
	...props
}: React.ComponentProps<typeof CommandPrimitive.Item>) => {
	return (
		<CommandPrimitive.Item
			data-slot='command-item'
			className={cn(
				"data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground [&_svg:not([class*='text-'])]:text-muted-foreground relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
				className,
			)}
			{...props}
		/>
	);
};
TypeScript
복사

CommandList에 표시 되는 Item 컴포넌트이다.

CommandShortcut

const CommandShortcut = ({
	className,
	...props
}: React.ComponentProps<'span'>) => {
	return (
		<span
			data-slot='command-shortcut'
			className={cn(
				'text-muted-foreground ml-auto text-xs tracking-widest',
				className,
			)}
			{...props}
		/>
	);
};
TypeScript
복사

Command 메뉴에서 단축키 표시용 컴포넌트이다. ml-auto를 통해 오른쪽 끝에 배치하며 tracking-widest로 넓은 자간을 적용했다.

Command

Context

Agenda

Contents