Bottom Sheet

화면 하단에서 올라오는 시트 컴포넌트로, 드래그·snap·dismiss 상호작용을 제공합니다.

사용 가능 버전@seed-design/lynx-react@0.1.0, @seed-design/lynx-css@0.1.0

Lynx 예제를 불러오는 중입니다.

import "./styles";

import { root, useRef, useState } from "@lynx-js/react";
import {
  ActionButton,
  BottomSheet,
  type BottomSheetRootRef,
  useSeedClassName,
  VStack,
} from "@seed-design/lynx-react";

function Root() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  const sheetRef = useRef<BottomSheetRootRef>(null);
  const [open, setOpen] = useState(false);

  function handleClose() {
    "background only";
    sheetRef.current?.close();
  }

  return (
    <page className={seedClassName}>
      <VStack className="bottom-sheet-preview" gap="x3">
        <text className="bottom-sheet-preview__status">
          {open ? "열림: true" : "열림: false"}
        </text>
        <BottomSheet.Root ref={sheetRef} onOpenChange={setOpen}>
          <BottomSheet.Trigger>
            <ActionButton variant="neutralSolid">Bottom Sheet 열기</ActionButton>
          </BottomSheet.Trigger>
          <BottomSheet.Positioner>
            <BottomSheet.Backdrop />
            <BottomSheet.Content>
              <BottomSheet.Header>
                <BottomSheet.Title>Bottom Sheet</BottomSheet.Title>
                <BottomSheet.Description>
                  배경을 탭하거나 아래로 밀어서도 닫을 수 있어요.
                </BottomSheet.Description>
              </BottomSheet.Header>
              <BottomSheet.Body className="bottom-sheet-preview__body">
                <text className="bottom-sheet-preview__body-text">본문 콘텐츠</text>
              </BottomSheet.Body>
              <BottomSheet.Footer>
                <ActionButton variant="neutralSolid" bindtap={handleClose}>
                  확인하고 닫기
                </ActionButton>
              </BottomSheet.Footer>
            </BottomSheet.Content>
          </BottomSheet.Positioner>
        </BottomSheet.Root>
      </VStack>
    </page>
  );
}

root.render(<Root />);

Installation

npx @seed-design/cli add ui:bottom-sheet

pnpm dlx @seed-design/cli add ui:bottom-sheet

yarn dlx @seed-design/cli add ui:bottom-sheet

bun x @seed-design/cli add ui:bottom-sheet

의존성 설치

npm install @seed-design/lynx-react

yarn add @seed-design/lynx-react

pnpm add @seed-design/lynx-react

bun add @seed-design/lynx-react

아래 코드를 복사 후 붙여넣고 사용하세요

/**
 * @file ui:bottom-sheet
 * @requires @seed-design/lynx-react@>=0.1.0 <1.0.0
 * @requires @seed-design/lynx-css@>=0.1.0 <1.0.0
 **/

import {
  BottomSheet as SeedBottomSheet,
  type BottomSheetBodyProps as SeedBottomSheetBodyProps,
  type BottomSheetContentProps as SeedBottomSheetContentProps,
  type BottomSheetFooterProps as SeedBottomSheetFooterProps,
  type BottomSheetRootProps as SeedBottomSheetRootProps,
  type BottomSheetRootRef as SeedBottomSheetRootRef,
  type BottomSheetTriggerProps as SeedBottomSheetTriggerProps,
} from "@seed-design/lynx-react";
import {
  forwardRef,
  type ForwardRefExoticComponent,
  type PropsWithoutRef,
  type ReactNode,
  type RefAttributes,
} from "@lynx-js/react";

export interface BottomSheetRootProps extends SeedBottomSheetRootProps {}

export type BottomSheetRootRef = SeedBottomSheetRootRef;

/**
 * @see https://seed-design.io/lynx/components/bottom-sheet
 */
export const BottomSheetRoot: ForwardRefExoticComponent<
  PropsWithoutRef<BottomSheetRootProps> & RefAttributes<SeedBottomSheetRootRef>
> = forwardRef<SeedBottomSheetRootRef, BottomSheetRootProps>((props, ref) => {
  return <SeedBottomSheet.Root ref={ref} {...props} />;
});
BottomSheetRoot.displayName = "BottomSheetRoot";

export interface BottomSheetTriggerProps extends SeedBottomSheetTriggerProps {}

export const BottomSheetTrigger = SeedBottomSheet.Trigger;

export interface BottomSheetContentProps extends Omit<SeedBottomSheetContentProps, "title"> {
  title?: ReactNode;

  description?: ReactNode;

  /**
   * @default false
   */
  showHandle?: boolean;
}

/**
 * Positioner / Backdrop / Handle / Header / Title / Description을 내부에서 조립해
 * 사용자가 단일 컴포넌트로 콘텐츠를 구성할 수 있도록 한다.
 *
 * 웹 BottomSheetContent와 달리 아래는 Lynx에서 미지원:
 * - `showCloseButton` (Tier B: SVG 지원 후 추가 예정)
 * - `accessibility-label` 기반 VisuallyHidden 제목 fallback (VisuallyHidden 미구현)
 */
export const BottomSheetContent = (props: BottomSheetContentProps) => {
  const { children, title, description, showHandle = false, ...otherProps } = props;

  const shouldRenderHeader = title || description;

  return (
    <SeedBottomSheet.Positioner>
      <SeedBottomSheet.Backdrop />
      <SeedBottomSheet.Content {...otherProps}>
        {showHandle && <SeedBottomSheet.Handle />}
        {shouldRenderHeader && (
          <SeedBottomSheet.Header>
            {title && <SeedBottomSheet.Title>{title}</SeedBottomSheet.Title>}
            {description && (
              <SeedBottomSheet.Description>{description}</SeedBottomSheet.Description>
            )}
          </SeedBottomSheet.Header>
        )}
        {children}
      </SeedBottomSheet.Content>
    </SeedBottomSheet.Positioner>
  );
};

export interface BottomSheetBodyProps extends SeedBottomSheetBodyProps {}

export const BottomSheetBody: (props: BottomSheetBodyProps) => ReactNode = SeedBottomSheet.Body;

export interface BottomSheetFooterProps extends SeedBottomSheetFooterProps {}

export const BottomSheetFooter: (props: BottomSheetFooterProps) => ReactNode =
  SeedBottomSheet.Footer;

/**
 * This file is a snippet from SEED Design, helping you get started quickly with @seed-design/* packages.
 * You can extend this snippet however you want.
 */

@seed-design/lynx-react의 BottomSheet는 @lynx-js/lynx-ui-sheet를 래핑합니다. 드래그·스프링·snap·presence 로직은 lynx-ui-sheet가 담당하고, SEED는 공개 API와 recipe 슬롯 스타일만 제공합니다. @seed-design/lynx-react를 설치하면 @lynx-js/lynx-ui-sheet도 함께 설치됩니다.

Usage

import {
  BottomSheetBody,
  BottomSheetContent,
  BottomSheetFooter,
  BottomSheetRoot,
  BottomSheetTrigger,
} from "@/components/ui/bottom-sheet";

export function App() {
  return (
    <BottomSheetRoot snapPoints={["fit", "80%"]}>
      <BottomSheetTrigger>
        <text>시트 열기</text>
      </BottomSheetTrigger>
      <BottomSheetContent title="제목" description="부가 설명" showHandle>
        <BottomSheetBody>
          <text>본문 콘텐츠</text>
        </BottomSheetBody>
        <BottomSheetFooter>
          <text>하단 액션 영역</text>
        </BottomSheetFooter>
      </BottomSheetContent>
    </BottomSheetRoot>
  );
}

snippet의 BottomSheetContent는 내부에서 Positioner, Backdrop, Content, Header, Title, Description을 조립합니다. BottomSheetTrigger는 Content 밖에 두어야 탭으로 시트를 열 수 있습니다.

본문 콘텐츠가 길어지는 경우 BottomSheetBody에 넣으면 세로 스크롤 영역으로 렌더링됩니다. 스크롤 가능한 긴 본문에서는 BottomSheetRoot에 handleOnly를 함께 사용해 시트 드래그를 handle로 제한하고, 본문 위의 세로 제스처는 body 스크롤에 사용하세요.

<BottomSheetRoot handleOnly snapPoints={["80%"]}>
  <BottomSheetTrigger>
    <text>긴 본문 열기</text>
  </BottomSheetTrigger>
  <BottomSheetContent title="제목" showHandle>
    <BottomSheetBody>{/* 긴 본문 */}</BottomSheetBody>
  </BottomSheetContent>
</BottomSheetRoot>

Imperative 제어

BottomSheetRoot에 ref를 전달하면 open, close, snapTo, expand, collapse 메서드를 호출할 수 있습니다.

import { useRef } from "@lynx-js/react";
import { BottomSheetRoot, type BottomSheetRootRef } from "@/components/ui/bottom-sheet";

export function App() {
  const ref = useRef<BottomSheetRootRef>(null);

  return (
    <BottomSheetRoot ref={ref} snapPoints={["fit", "80%"]}>
      {/* ... */}
    </BottomSheetRoot>
  );
}

Props

`BottomSheetRoot`

Prop

Type

`BottomSheetTrigger`

Prop

Type

style?CSSProperties | undefined

children?ReactNode

className?string | undefined

bindtap?EventHandler<BaseTouchEvent<Target>> | undefined

`BottomSheetContent`

Prop

Type

title?ReactNode

description?ReactNode

`BottomSheetBody`

Prop

Type

style?CSSProperties | undefined

children?ReactNode

className?string | undefined

`BottomSheetFooter`

Prop

Type

style?CSSProperties | undefined

children?ReactNode

className?string | undefined

Examples

Trigger

BottomSheet.Trigger를 탭하면 Bottom Sheet가 열립니다. Lynx에서는 asChild를 지원하지 않으므로 Trigger가 자식 요소를 감싸는 <view>를 렌더링합니다.

Footer의 버튼, 배경 탭, 아래 방향 드래그로 Bottom Sheet를 닫을 수 있습니다. 예제 위쪽의 상태 값에서 onOpenChange 결과를 확인할 수 있습니다.

Lynx 예제를 불러오는 중입니다.

import "./styles";

import { root, useRef, useState } from "@lynx-js/react";
import {
  ActionButton,
  BottomSheet,
  type BottomSheetRootRef,
  useSeedClassName,
  VStack,
} from "@seed-design/lynx-react";

function Root() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  const sheetRef = useRef<BottomSheetRootRef>(null);
  const [open, setOpen] = useState(false);

  function handleClose() {
    "background only";
    sheetRef.current?.close();
  }

  return (
    <page className={seedClassName}>
      <VStack className="bottom-sheet-preview" gap="x3">
        <text className="bottom-sheet-preview__status">
          {open ? "열림: true" : "열림: false"}
        </text>
        <BottomSheet.Root ref={sheetRef} onOpenChange={setOpen}>
          <BottomSheet.Trigger>
            <ActionButton variant="neutralSolid">Bottom Sheet 열기</ActionButton>
          </BottomSheet.Trigger>
          <BottomSheet.Positioner>
            <BottomSheet.Backdrop />
            <BottomSheet.Content>
              <BottomSheet.Header>
                <BottomSheet.Title>Bottom Sheet</BottomSheet.Title>
                <BottomSheet.Description>
                  배경을 탭하거나 아래로 밀어서도 닫을 수 있어요.
                </BottomSheet.Description>
              </BottomSheet.Header>
              <BottomSheet.Body className="bottom-sheet-preview__body">
                <text className="bottom-sheet-preview__body-text">본문 콘텐츠</text>
              </BottomSheet.Body>
              <BottomSheet.Footer>
                <ActionButton variant="neutralSolid" bindtap={handleClose}>
                  확인하고 닫기
                </ActionButton>
              </BottomSheet.Footer>
            </BottomSheet.Content>
          </BottomSheet.Positioner>
        </BottomSheet.Root>
      </VStack>
    </page>
  );
}

root.render(<Root />);

Controlled

Trigger 외의 방식으로 Bottom Sheet를 열고 닫으려면 open과 onOpenChange로 상태를 제어합니다. 배경 탭이나 드래그로 닫을 때도 onOpenChange가 호출되므로 전달받은 값을 open에 반영해야 합니다.

Lynx 예제를 불러오는 중입니다.

import "./styles";

import { root, useState } from "@lynx-js/react";
import { ActionButton, BottomSheet, useSeedClassName, VStack } from "@seed-design/lynx-react";

function Root() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  const [open, setOpen] = useState(false);

  function handleOpen() {
    "background only";
    setOpen(true);
  }

  function handleClose() {
    "background only";
    setOpen(false);
  }

  return (
    <page className={seedClassName}>
      <VStack className="bottom-sheet-preview" gap="x3">
        <text className="bottom-sheet-preview__status">
          {open ? "open: true" : "open: false"}
        </text>
        <ActionButton variant="neutralSolid" bindtap={handleOpen} disabled={open}>
          상태로 열기
        </ActionButton>
        <BottomSheet.Root open={open} onOpenChange={setOpen}>
          <BottomSheet.Positioner>
            <BottomSheet.Backdrop />
            <BottomSheet.Content>
              <BottomSheet.Header>
                <BottomSheet.Title>Controlled Bottom Sheet</BottomSheet.Title>
                <BottomSheet.Description>
                  open 값과 onOpenChange로 열린 상태를 제어합니다.
                </BottomSheet.Description>
              </BottomSheet.Header>
              <BottomSheet.Body className="bottom-sheet-preview__body">
                <text className="bottom-sheet-preview__body-text">
                  {open ? "현재 open: true" : "현재 open: false"}
                </text>
              </BottomSheet.Body>
              <BottomSheet.Footer>
                <ActionButton variant="neutralSolid" bindtap={handleClose}>
                  상태로 닫기
                </ActionButton>
              </BottomSheet.Footer>
            </BottomSheet.Content>
          </BottomSheet.Positioner>
        </BottomSheet.Root>
      </VStack>
    </page>
  );
}

root.render(<Root />);

Snap Points

snapPoints에는 픽셀 숫자, 화면 높이 기준 백분율, 콘텐츠 크기에 맞추는 "fit"을 사용할 수 있습니다. 배열 순서가 snap index가 되며, initialSnap으로 처음 열릴 높이를 정합니다.

onSnapChange에서는 현재 index와 픽셀로 계산된 높이를 받을 수 있습니다. ref의 snapTo 메서드를 사용하면 원하는 높이로 이동할 수 있습니다.

Lynx 예제를 불러오는 중입니다.

import "./styles";

import { root, useRef, useState } from "@lynx-js/react";
import {
  ActionButton,
  BottomSheet,
  type BottomSheetRootRef,
  HStack,
  useSeedClassName,
  VStack,
} from "@seed-design/lynx-react";

const snapPoints = ["45%", "80%"];

function Root() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  const sheetRef = useRef<BottomSheetRootRef>(null);
  const [snapIndex, setSnapIndex] = useState(0);

  function handleSnapToFirst() {
    "background only";
    sheetRef.current?.snapTo(0);
  }

  function handleSnapToSecond() {
    "background only";
    sheetRef.current?.snapTo(1);
  }

  function handleClose() {
    "background only";
    sheetRef.current?.close();
  }

  return (
    <page className={seedClassName}>
      <VStack className="bottom-sheet-preview" gap="x3">
        <text className="bottom-sheet-preview__status">
          snap index: {JSON.stringify(snapIndex)}
        </text>
        <BottomSheet.Root
          ref={sheetRef}
          snapPoints={snapPoints}
          initialSnap={0}
          onSnapChange={(index) => setSnapIndex(index)}
        >
          <BottomSheet.Trigger>
            <ActionButton variant="neutralSolid">Snap Points 열기</ActionButton>
          </BottomSheet.Trigger>
          <BottomSheet.Positioner>
            <BottomSheet.Backdrop />
            <BottomSheet.Content>
              <BottomSheet.Handle />
              <BottomSheet.Header>
                <BottomSheet.Title>Snap Points</BottomSheet.Title>
                <BottomSheet.Description>
                  핸들을 드래그하거나 버튼을 탭해 높이를 바꿔 보세요.
                </BottomSheet.Description>
              </BottomSheet.Header>
              <BottomSheet.Body className="bottom-sheet-preview__snap-body">
                <text className="bottom-sheet-preview__body-text">
                  현재 snap index: {JSON.stringify(snapIndex)}
                </text>
                <HStack gap="x2">
                  <ActionButton flexGrow={1} variant="neutralWeak" bindtap={handleSnapToFirst}>
                    45%
                  </ActionButton>
                  <ActionButton flexGrow={1} variant="neutralWeak" bindtap={handleSnapToSecond}>
                    80%
                  </ActionButton>
                </HStack>
              </BottomSheet.Body>
              <BottomSheet.Footer>
                <ActionButton variant="neutralSolid" bindtap={handleClose}>
                  닫기
                </ActionButton>
              </BottomSheet.Footer>
            </BottomSheet.Content>
          </BottomSheet.Positioner>
        </BottomSheet.Root>
      </VStack>
    </page>
  );
}

root.render(<Root />);

드래그와 snap 애니메이션의 최종 동작은 QR 코드 탭에서 Lynx Explorer로 확인하세요. 문서 미리보기에서는 기기와 제스처 처리 결과가 다를 수 있습니다.

웹 버전과의 차이

Lynx BottomSheet는 React BottomSheet와 다음과 같은 차이가 있습니다.

이벤트 핸들링: onClick 대신 bindtap을 사용합니다.
렌더링 요소: HTML <div> 대신 네이티브 <view>/<text> 요소를 렌더링합니다.
내부 엔진: Radix Drawer 대신 @lynx-js/lynx-ui-sheet를 래핑합니다.

항목	웹	Lynx
상태 prop	`open`/`defaultOpen`/`onOpenChange`	동일 (내부에서 lynx-ui-sheet의 `show`/`defaultShow`/`onShowChange`로 매핑)
`onOpenChange`의 `details.reason`	지원	미지원 — 변경된 `open` 값만 전달
마운트 제어	`lazyMount`, `unmountOnExit`	미지원 — `forceMount`로 대체
`BottomSheetPositioner`	존재	동일 (lynx-ui-sheet의 `SheetView` 래핑) — 첫 open 전까지 Backdrop/Content 마운트 지연
`BottomSheetCloseButton`	존재	미포함 — Tier B (SVG 지원 후 추가 예정)
`snapPoints`	지원	지원 (`(number \| string)[]`, 기본값 `["fit"]`)
`BottomSheetTrigger`의 `asChild`	지원	미지원 (기본 `<view>`로만 렌더링)
imperative ref API	—	`BottomSheetRootRef.{open, close, snapTo, expand, collapse}`

Lynx 미지원 기능

현재 Lynx 플랫폼 제약으로 다음 기능이 지원되지 않습니다.

Lynx SVG 지원 후 추가 예정

기능	웹 대응	설명
`BottomSheetCloseButton`	`BottomSheet.CloseButton`	X 아이콘 SVG 필요

마운트 수명주기

기능	웹 대응	대체 방법
`lazyMount`	`BottomSheet.Root` prop	`forceMount={false}` (기본값) — 기본적으로 열릴 때만 마운트
`unmountOnExit`	`BottomSheet.Root` prop	`forceMount`로 제어 — lynx-ui-sheet의 presence 상태 머신이 자연스럽게 언마운트 처리

Bottom Sheet

Manual Installation

의존성 설치

아래 코드를 복사 후 붙여넣고 사용하세요

목차