Bottom Sheet

화면 하단에서 올라오는 모달 컴포넌트예요. 추가 정보나 액션 목록을 제공하면서도 현재 컨텍스트를 유지할 때 사용해요.

설치

pnpm dlx shadcn@latest add https://rebar.conmarket-landing.workers.dev/r/bottom-sheet.json

pnpm dlx shadcn@latest add https://rebar.conmarket-landing.workers.dev/r/bottom-sheet.json

vaul, class-variance-authority, lucide-react 를 설치하고 아래 코드를 components/ui/bottom-sheet.tsx 에 복사해요.

components/ui/bottom-sheet.tsx

/** * @title Bottom Sheet * @description 화면 하단에서 올라오는 모달 컴포넌트예요. 현재 맥락을 유지하면서 추가 정보나 액션을 보여줄 때 사용해요. */'use client';import * as React from 'react';import { Drawer as DrawerPrimitive } from 'vaul';import { cva } from 'class-variance-authority';import { XIcon } from 'lucide-react';import { cn } from '@/lib/utils';// SEED Rootage spec: bottom-sheet.yaml, bottom-sheet-handle.yaml, bottom-sheet-close-button.yamltype HeaderAlign = 'left' | 'center';interface BottomSheetContextValue {  headerAlign: HeaderAlign;}const BottomSheetContext = React.createContext<BottomSheetContextValue>({ headerAlign: 'left' });type BottomSheetProps = React.ComponentProps<typeof DrawerPrimitive.Root> & {  /** Title 과 Description 의 정렬이에요. */  headerAlign?: HeaderAlign;};function BottomSheet({ headerAlign = 'left', ...props }: BottomSheetProps) {  const value = React.useMemo(() => ({ headerAlign }), [headerAlign]);  return (    <BottomSheetContext.Provider value={value}>      <DrawerPrimitive.Root data-slot="bottom-sheet" {...props} />    </BottomSheetContext.Provider>  );}function BottomSheetTrigger(props: React.ComponentProps<typeof DrawerPrimitive.Trigger>) {  return <DrawerPrimitive.Trigger data-slot="bottom-sheet-trigger" {...props} />;}function BottomSheetClose(props: React.ComponentProps<typeof DrawerPrimitive.Close>) {  return <DrawerPrimitive.Close data-slot="bottom-sheet-close" {...props} />;}function BottomSheetPortal(props: React.ComponentProps<typeof DrawerPrimitive.Portal>) {  return <DrawerPrimitive.Portal data-slot="bottom-sheet-portal" {...props} />;}function BottomSheetBackdrop({ className, ...props }: React.ComponentProps<typeof DrawerPrimitive.Overlay>) {  return (    <DrawerPrimitive.Overlay      data-slot="bottom-sheet-backdrop"      className={cn(        'fixed inset-0 z-50 bg-bg-overlay',        // backdrop: enter d6 / enter, exit d4 / exit (vaul 기본 애니메이션 값을 덮어써요)        'data-[state=open]:[animation-duration:var(--rb-duration-d6)]! data-[state=open]:[animation-timing-function:var(--rb-timing-function-enter)]!',        'data-[state=closed]:[animation-duration:var(--rb-duration-d4)]! data-[state=closed]:[animation-timing-function:var(--rb-timing-function-exit)]!',        className,      )}      {...props}    />  );}function BottomSheetHandle({ className, ...props }: React.ComponentProps<typeof DrawerPrimitive.Handle>) {  return (    <DrawerPrimitive.Handle      data-slot="bottom-sheet-handle"      className={cn(        // vaul 이 주입하는 핸들 스타일을 SEED 스펙(36x4, gray-400, top 6px)으로 덮어써요.        'absolute! top-[6px]! left-1/2! m-0! h-[4px]! w-[36px]! -translate-x-1/2 rounded-full! bg-palette-gray-400! opacity-100!',        'transition-[background-color] duration-(--rb-duration-color-transition) ease-easing active:bg-palette-gray-500!',        className,      )}      {...props}    />  );}interface BottomSheetContentProps extends Omit<React.ComponentProps<typeof DrawerPrimitive.Content>, 'title'> {  title?: React.ReactNode;  description?: React.ReactNode;  /** @default true */  showCloseButton?: boolean;  /** @default false */  showHandle?: boolean;}function BottomSheetContent({  className,  children,  title,  description,  showCloseButton = true,  showHandle = false,  ...props}: BottomSheetContentProps) {  const shouldRenderHeader = Boolean(title || description);  return (    <BottomSheetPortal>      <BottomSheetBackdrop />      <DrawerPrimitive.Content        data-slot="bottom-sheet-content"        className={cn(          'fixed inset-x-0 bottom-0 z-50 mx-auto flex w-full max-w-[480px] flex-col break-all outline-none',          'max-h-[min(90dvh,100dvh_-_env(safe-area-inset-top))] rounded-t-r6 bg-bg-layer-floating pb-[env(safe-area-inset-bottom)]',          // content: enter d6 / enter-expressive, exit d4 / exit          'data-[state=open]:[animation-duration:var(--rb-duration-d6)]! data-[state=open]:[animation-timing-function:var(--rb-timing-function-enter-expressive)]!',          'data-[state=closed]:[animation-duration:var(--rb-duration-d4)]! data-[state=closed]:[animation-timing-function:var(--rb-timing-function-exit)]!',          className,        )}        {...props}      >        {showHandle && <BottomSheetHandle />}        {shouldRenderHeader ? (          <BottomSheetHeader>            {title ? (              <BottomSheetTitle showCloseButton={showCloseButton}>{title}</BottomSheetTitle>            ) : (              <DrawerPrimitive.Title className="sr-only">{props['aria-label'] ?? ''}</DrawerPrimitive.Title>            )}            {description && <BottomSheetDescription>{description}</BottomSheetDescription>}          </BottomSheetHeader>        ) : (          <DrawerPrimitive.Title className="sr-only">{props['aria-label'] ?? ''}</DrawerPrimitive.Title>        )}        {children}        {showCloseButton && <BottomSheetCloseButton />}      </DrawerPrimitive.Content>    </BottomSheetPortal>  );}function BottomSheetHeader({ className, ...props }: React.ComponentProps<'div'>) {  const { headerAlign } = React.useContext(BottomSheetContext);  return (    <div      data-slot="bottom-sheet-header"      data-header-align={headerAlign}      className={cn(        'flex flex-col gap-x2 pt-x6 pb-x4',        headerAlign === 'center' ? 'justify-center text-center' : 'justify-start',        className,      )}      {...props}    />  );}const bottomSheetTitleVariants = cva('m-0 text-t8 font-bold text-fg-neutral break-keep', {  variants: {    headerAlign: { left: '', center: '' },    showCloseButton: { true: '', false: '' },  },  compoundVariants: [    { headerAlign: 'left', showCloseButton: true, className: 'pr-[56px] pl-spacing-x-global-gutter' },    { headerAlign: 'left', showCloseButton: false, className: 'px-spacing-x-global-gutter' },    { headerAlign: 'center', showCloseButton: true, className: 'px-[56px]' },    { headerAlign: 'center', showCloseButton: false, className: 'px-spacing-x-global-gutter' },  ],  defaultVariants: { headerAlign: 'left', showCloseButton: true },});function BottomSheetTitle({  className,  showCloseButton = true,  ...props}: React.ComponentProps<typeof DrawerPrimitive.Title> & { showCloseButton?: boolean }) {  const { headerAlign } = React.useContext(BottomSheetContext);  return (    <DrawerPrimitive.Title      data-slot="bottom-sheet-title"      data-show-close-button={showCloseButton || undefined}      className={cn(bottomSheetTitleVariants({ headerAlign, showCloseButton }), className)}      {...props}    />  );}function BottomSheetDescription({ className, ...props }: React.ComponentProps<typeof DrawerPrimitive.Description>) {  return (    <DrawerPrimitive.Description      data-slot="bottom-sheet-description"      className={cn(        'm-0 px-spacing-x-global-gutter text-t5 font-regular whitespace-pre-wrap text-fg-neutral-muted',        className,      )}      {...props}    />  );}interface BottomSheetBodyProps extends React.ComponentProps<'div'> {  /** Body 의 최대 높이예요. 넘치면 Body 안에서 스크롤돼요. */  maxHeight?: React.CSSProperties['maxHeight'];}function BottomSheetBody({ className, maxHeight, style, ...props }: BottomSheetBodyProps) {  return (    <div      data-slot="bottom-sheet-body"      className={cn('flex min-h-0 flex-col overflow-y-auto px-spacing-x-global-gutter', className)}      style={maxHeight !== undefined ? { maxHeight, ...style } : style}      {...props}    />  );}function BottomSheetFooter({ className, ...props }: React.ComponentProps<'div'>) {  return (    <div      data-slot="bottom-sheet-footer"      className={cn('flex flex-col px-spacing-x-global-gutter pt-x3 pb-x4', className)}      {...props}    />  );}function BottomSheetCloseButton({  className,  children,  'aria-label': ariaLabel = '닫기',  ...props}: React.ComponentProps<typeof DrawerPrimitive.Close>) {  return (    <DrawerPrimitive.Close      data-slot="bottom-sheet-close-button"      aria-label={ariaLabel}      className={cn(        'absolute top-x6 right-x4 flex size-[28px] cursor-pointer items-center justify-center rounded-full border-none bg-bg-neutral-weak text-fg-neutral',        // 44px 터치 영역        "after:absolute after:-inset-[8px] after:rounded-r1 after:content-['']",        'transition-[background-color,scale,outline-color] duration-(--rb-duration-color-transition) ease-easing',        'outline-2 outline-offset-2 outline-transparent focus-visible:outline-stroke-focus-ring',        'active:scale-[0.95] active:bg-bg-neutral-weak-pressed',        '[&_svg]:pointer-events-none [&_svg]:size-[14px] [&_svg]:shrink-0',        className,      )}      {...props}    >      {children ?? <XIcon strokeWidth={2.5} />}    </DrawerPrimitive.Close>  );}export {  BottomSheet,  BottomSheetTrigger,  BottomSheetClose,  BottomSheetPortal,  BottomSheetBackdrop,  BottomSheetHandle,  BottomSheetContent,  BottomSheetHeader,  BottomSheetTitle,  BottomSheetDescription,  BottomSheetBody,  BottomSheetFooter,  BottomSheetCloseButton,};export type { BottomSheetProps, BottomSheetContentProps, BottomSheetBodyProps };

Anatomy

Bottom Sheet는 Backdrop, Container, Header, Close Button, Footer가 조합되어 제공돼요.

영역	컴포넌트	설명
Backdrop	`BottomSheetBackdrop`	시트 뒤 화면을 어둡게 덮어요. `BottomSheetContent` 가 자동으로 그려요.
Container	`BottomSheetContent`	상단 모서리가 둥근 시트 본체예요. 최대 너비 480px, 최대 높이는 화면의 90%예요.
Handle	`showHandle`	드래그로 닫거나 스냅 포인트를 오갈 때 쓰는 손잡이예요.
Header	`title`, `description`	Title과 Description으로 구성돼요.
Close Button	`showCloseButton`	오른쪽 위의 닫기 버튼이에요.
Content Area	`BottomSheetBody`	자유롭게 콘텐츠를 담는 영역이에요. 넘치면 이 안에서 스크롤돼요.
Footer	`BottomSheetFooter`	하단 CTA 영역이에요.

<BottomSheet>
  <BottomSheetTrigger asChild>
    <ActionButton>열기</ActionButton>
  </BottomSheetTrigger>
  <BottomSheetContent title="제목" description="설명">
    <BottomSheetBody>{/* 콘텐츠 */}</BottomSheetBody>
    <BottomSheetFooter>
      <ActionButton size="large">확인</ActionButton>
    </BottomSheetFooter>
  </BottomSheetContent>
</BottomSheet>

Properties

Header는 Title과 Description으로 구성되며 콘텐츠에 따라 정렬을 바꿀 수 있어요. <BottomSheet> 에 headerAlign 을 left 또는 center 로 지정해요.

Show Handle

Bottom Sheet를 드래그로 닫거나, 스냅 포인트를 설정해 확장 및 축소할 수 있는 Handle을 표시할 수 있어요. Handle은 Enabled와 Pressed 상태를 가져요. 기본값은 false 예요.

Show Close Button

Close Button 사용 여부를 정해요. 기본값은 true 예요. Close Button은 28px 크기지만, 내부에 터치 영역을 보장하는 44px 프레임이 포함되어 있어요.

showCloseButton={false} 로 닫기 버튼을 숨기면 사용자가 시트를 닫을 수 있는 다른 방법을 꼭 제공해야 해요.

Show Description

Header를 사용할 경우 Title은 반드시 포함되어야 하고, Description은 부가 설명을 위해 추가할 수 있어요.

Footer 사용 여부를 정해요. BottomSheetFooter 안에 버튼을 넣어 하단 CTA를 구성해요.

Snap Points

snapPoints 로 시트를 여러 높이에 멈추게 할 수 있어요. 화면 비율(0~1)이나 픽셀('240px')로 지정해요. 스냅 포인트를 쓸 때는 Handle을 반드시 표시해요.

Controlled

Trigger 외의 방식으로 시트를 열고 닫을 때는 open 과 onOpenChange 로 상태를 직접 제어해요.

Dismissible

dismissible={false} 로 지정하면 ESC, 바깥 영역 터치, 드래그로 닫히지 않아요. 이 경우에도 사용자가 시트를 닫을 수 있는 방법을 제공해야 해요.

Guidelines

Content Area

Bottom Sheet는 콘텐츠의 양과 사용 가능한 공간에 따라 유연하게 크기가 조정되고 모든 요소를 담을 수 있어요. Content Area의 크기는 내부에 담긴 요소들이 차지하는 공간에 따라 정해져요.

최대 너비

Bottom Sheet는 화면 너비 최대 480px까지 보여요. 그보다 넓은 화면에서는 가운데에 놓여요.

닫기 동작

Bottom Sheet는 기본적으로 아래로 드래그하거나 바깥을 누르면 닫혀요. 필요에 따라 상단이나 하단 CTA에 닫는 동작을 추가할 수 있어요.

복잡한 양식을 작성하거나 결제할 때처럼 실수하면 안 되는 중요한 작업이나, Bottom Sheet 안에서 화면이 바뀔 때는 상단에 닫기 버튼을 넣는 것이 좋아요. 이런 경우에는 핸들을 제거해서 실수로 닫히는 것을 막는 것을 권장해요.

Snap Point 사용하기

Bottom Sheet에 Snap Point를 추가해 시트의 높이를 확장하거나 축소할 수 있어요.

스냅 포인트는 최소 2개(최대, 중간)를 설정하고, 필요하면 3개(최대, 중간, 최소)까지 설정할 수 있어요.
권장 값은 최대(화면의 90%), 중간(50%), 최소(10%)예요.
Snap Point를 추가하는 경우 Handle을 반드시 표시해요.

최대 높이와 스크롤

Bottom Sheet의 최대 높이는 화면 전체 높이의 90%를 넘지 않는 것을 권장해요. 콘텐츠가 많아 90%를 넘는다면 스크롤보다는 별도 페이지로 표현하는 것을 권장해요.

해상도 등으로 스크롤이 생기는 경우, 스크롤은 Content Area(BottomSheetBody) 안에서만 일어나요.

Title, Description의 길이

알림을 켤까요?가격이 내려가면 알려드려요.

Do· 짧고 명확한 문구

Title과 Description은 한눈에 읽히도록 짧게 써요.

관심 상품의 가격이 내려가거나 새 상품이 올라오면 알림을 받으시겠어요?알림을 켜면 관심 상품의 가격 변동, 새 상품 등록, 판매 완료 소식을 모두 받아볼 수 있어요.

Don't· 너무 긴 문구

글이 너무 길어지지 않도록 주의해요.

Bottom Sheet

설치

Anatomy

Properties

Header Layout

Show Handle

Show Close Button

Show Description

Show Footer

Snap Points

Controlled

Dismissible

Guidelines

Content Area

최대 너비

닫기 동작

Snap Point 사용하기

최대 높이와 스크롤

Title, Description의 길이

키보드가 나타날 경우

Props

BottomSheet

BottomSheetContent

BottomSheetBody

On this page

Bottom Sheet

설치Copy Anchor Link

수동 설치

AnatomyCopy Anchor Link

PropertiesCopy Anchor Link

Header LayoutCopy Anchor Link

Show HandleCopy Anchor Link

Show Close ButtonCopy Anchor Link

Show DescriptionCopy Anchor Link

Show FooterCopy Anchor Link

Snap PointsCopy Anchor Link

ControlledCopy Anchor Link

DismissibleCopy Anchor Link

GuidelinesCopy Anchor Link

Content AreaCopy Anchor Link

최대 너비Copy Anchor Link

닫기 동작Copy Anchor Link

Snap Point 사용하기Copy Anchor Link

최대 높이와 스크롤Copy Anchor Link

Title, Description의 길이Copy Anchor Link

키보드가 나타날 경우Copy Anchor Link

PropsCopy Anchor Link

BottomSheetCopy Anchor Link

BottomSheetContentCopy Anchor Link

BottomSheetBodyCopy Anchor Link

On this page

설치

Anatomy

Properties

Header Layout

Show Handle

Show Close Button

Show Description

Show Footer

Snap Points

Controlled

Dismissible

Guidelines

Content Area

최대 너비

닫기 동작

Snap Point 사용하기

최대 높이와 스크롤

Title, Description의 길이

키보드가 나타날 경우

Props

BottomSheet

BottomSheetContent

BottomSheetBody