💡

Sheet

Created

2026/01/15 15:29

Context

shadcn/ui의 Sidebar 컴포넌트는 Mobile일 환경일 때 Sheet 컴포넌트를 활용하여 사이드바를 렌더링한다. Sheet 컴포넌트가 어떻게 쓰이는지, 왜 필요한지에 대해서 분석해보고자 한다.

Agenda

•

Sheet 관련 컴포넌트에 대해 분석하고 이해하는 것을 목표로 함.

Extends the Dialog component to display content that complements the main content of the screen.
Plain Text
복사

shadcn/ui의 Sheet docs 첫 부분에 있는 설명이다. Sheet 컴포넌트는 Dialog를 확장하여 화면에 부가적인 요소를 표현할 수 있도록 돕는 역할을 수행한다.

<Sheet>
  <SheetTrigger>Open</SheetTrigger>
  <SheetContent>
    <SheetHeader>
      <SheetTitle>Are you absolutely sure?</SheetTitle>
      <SheetDescription>
        This action cannot be undone. This will permanently delete your account
        and remove your data from our servers.
      </SheetDescription>
    </SheetHeader>
  </SheetContent>
</Sheet>
JavaScript
복사

공식 문서에 나와있는 Usage이다. Sheet부터 SheetDescription까지의 계층으로 구성 되어있는 것을 알 수 있다. Sidebar와 마찬가지로 SheetTrigger가 존재하며 이는 Sheet의 표시 상태를 관리하는 컴포넌트인 것 같다.

Sheet

import * as SheetPrimitive from '@radix-ui/react-dialog';

function Sheet({ ...props }: React.ComponentProps<typeof SheetPrimitive.Root>) {
	return <SheetPrimitive.Root data-slot='sheet' {...props} />;
}
TypeScript
복사

shadcn/ui의 sheet 파일에 처음으로 있는 컴포넌트이다. radix-ui의 react-dialog에서 나온 모듈을 사용하는 것을 알 수 있다. 이처럼 shadcn/ui는 radix-ui의 컴포넌트를 가져와서 사용하는 wrapper 처럼 컴포넌트를 구성한다. 이 Sheet 컴포넌트는 Root의 props를 그대로 받아낼 수 있고 사실상 Radix Dialog의 Root를 그대로 노출한다고 볼 수 있다. 아래는 Sheet가 받을 수 있는 파라미터의 종류.

(parameter) props: {
    children?: React.ReactNode;
    open?: boolean;
    defaultOpen?: boolean;
    onOpenChange?(open: boolean): void;
    modal?: boolean;
}
JavaScript
복사

SheetTrigger

function SheetTrigger({
	...props
}: React.ComponentProps<typeof SheetPrimitive.Trigger>) {
	return <SheetPrimitive.Trigger data-slot='sheet-trigger' {...props} />;
}
JavaScript
복사

SheetTrigger는 Sheet를 열 수 있는 컴포넌트이다. 마찬가지로 radix-ui의 Dialog의 Trigger를 감싸 렌더링 한다.

SheetClose

function SheetClose({
	...props
}: React.ComponentProps<typeof SheetPrimitive.Close>) {
	return <SheetPrimitive.Close data-slot='sheet-close' {...props} />;
}
TypeScript
복사

SheetClose는 Sheet를 닫을 수 있는 버튼 컴포넌트이다. radix-ui의 Dialog의 Close를 감싸서 렌더링한다.

SheetPortal

function SheetPortal({
	...props
}: React.ComponentProps<typeof SheetPrimitive.Portal>) {
	return <SheetPrimitive.Portal data-slot='sheet-portal' {...props} />;
}
TypeScript
복사

SheetPortal은 사용 시 overlay와 콘텐츠를 body에 렌더링 한다. 말이 살짝 이상하고 당연히 body에 렌더링 하는데, 이 Portal 기능은 z-index나 overflow 같은 렌더링 계층 문제를 해결하기 위해 컴포넌트를 논리적으로는 배치한 곳에 소속 시키지만 실제 렌더링은 body 태그와 가까운 곳에 렌더링한다.

SheetOverlay

function SheetOverlay({
	className,
	...props
}: React.ComponentProps<typeof SheetPrimitive.Overlay>) {
	return (
		<SheetPrimitive.Overlay
			data-slot='sheet-overlay'
			className={cn(
				'data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/50',
				className,
			)}
			{...props}
		/>
	);
}
TypeScript
복사

SheetOverlay 컴포넌트는 Sheet가 열렸을 때 뒤 배경을 어둡게 해주는 반투명 레이어이다. Backdrop 효과를 담당하는 컴포넌트이며 접근성, 포커스, 스크롤락과 같이 모달 배경을 구성하는 요소이다. 마찬가지로 radix-ui Dialog의 Overlay를 사용한다.

SheetContent

function SheetContent({
	className,
	children,
	side = 'right',
	...props
}: React.ComponentProps<typeof SheetPrimitive.Content> & {
	side?: 'top' | 'right' | 'bottom' | 'left';
}) {
	return (
		<SheetPortal>
			<SheetOverlay />
			<SheetPrimitive.Content
				data-slot='sheet-content'
				className={cn(
					'bg-background data-[state=open]:animate-in data-[state=closed]:animate-out fixed z-50 flex flex-col gap-4 shadow-lg transition ease-in-out data-[state=closed]:duration-300 data-[state=open]:duration-500',
					side === 'right' &&
						'data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right inset-y-0 right-0 h-full w-3/4 border-l sm:max-w-sm',
					side === 'left' &&
						'data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left inset-y-0 left-0 h-full w-3/4 border-r sm:max-w-sm',
					side === 'top' &&
						'data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top inset-x-0 top-0 h-auto border-b',
					side === 'bottom' &&
						'data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom inset-x-0 bottom-0 h-auto border-t',
					className,
				)}
				{...props}
			>
				{children}
				<SheetPrimitive.Close className='ring-offset-background focus:ring-ring data-[state=open]:bg-secondary absolute top-4 right-4 rounded-xs opacity-70 transition-opacity hover:opacity-100 focus:ring-2 focus:ring-offset-2 focus:outline-hidden disabled:pointer-events-none'>
					<XIcon className='size-4' />
					<span className='sr-only'>Close</span>
				</SheetPrimitive.Close>
			</SheetPrimitive.Content>
		</SheetPortal>
	);
}
TypeScript
복사

Sheet의 내용을 보여주는 컴포넌트이다. side 파라미터를 활용해 Sheet가 펼쳐지고 접히는 방향을 설정할 수 있다. 지금까지 Overlay의 children에 Content를 렌더링하는 방식으로 컴포넌트를 구현했었는데, shadcn/ui에서는 Overlay와 Content를 sibling depth에 두어 컴포넌트를 작성하였다. 아마 클릭과 같은 이벤트 처리와 컴포넌트 기능을 명확하게 구분하기 위한 구조가 아닐까 생각한다.

const SheetHeader = ({ className, ...props }: React.ComponentProps<'div'>) => {
	return (
		<div
			data-slot='sheet-header'
			className={cn('flex flex-col gap-1.5 p-4', className)}
			{...props}
		/>
	);
};

const SheetFooter = ({ className, ...props }: React.ComponentProps<'div'>) => {
	return (
		<div
			data-slot='sheet-footer'
			className={cn('mt-auto flex flex-col gap-2 p-4', className)}
			{...props}
		/>
	);
};
TypeScript
복사

Sheet의 Header와 Footer 컴포넌트이다. radix-ui의 컴포넌트를 사용하지 않고 구성되어있다.

Sidebar에서 사용된 예시를 보면 아래와 같이 sr-only를 활용하여 화면에는 안보이게 하고 스크린 리더 사용자에게 정보를 제공한다.

<SheetHeader className='sr-only'>
	<SheetTitle>Sidebar</SheetTitle>
	<SheetDescription>Displays the mobile sidebar.</SheetDescription>
</SheetHeader>
TypeScript
복사

const SheetTitle = ({
	className,
	...props
}: React.ComponentProps<typeof SheetPrimitive.Title>) => {
	return (
		<SheetPrimitive.Title
			data-slot='sheet-title'
			className={cn('text-foreground font-semibold', className)}
			{...props}
		/>
	);
};

const SheetDescription = ({
	className,
	...props
}: React.ComponentProps<typeof SheetPrimitive.Description>) => {
	return (
		<SheetPrimitive.Description
			data-slot='sheet-description'
			className={cn('text-muted-foreground text-sm', className)}
			{...props}
		/>
	);
};
TypeScript
복사

Sheet의 Title과 Description이다. 일반적으로 h2 태그와 p 태그를 활용해서 제목과 그 정보를 마크업 할 수 있으나 접근성 차원에서 Title과 Description을 사용하는 것 같다. 공식 문서에 보면 Title과 Description이 announced 된다고 나와있는데 아마 이런 맥락에서의 설명이라고 받아들여진다.

Sheet

Context

Agenda

Contents