For AI agents: the complete documentation index is available at /next/llms.txt, the full documentation bundle is available at /next/llms-full.txt, and this page is available as Markdown at /next/ui/components/sheet.md.
lynx-ui logo
lynx-ui
  • English
  • Sheet

    A directional Sheet component for ReactLynx. It supports bottom-sheet and side-drawer semantics with drag interactions and snap point primitives.
    • Supports controlled and uncontrolled visibility.
    • Supports snap points, including percentages and content-driven height.
    • Supports imperative control through SheetRootRef.
    Info

    You can check the source code to understand how it works, and you're welcome to submit MRs to enhance its capabilities.

    Sheet is a sliding surface for contextual actions, detail panels, and transient workflows. It supports bottom sheets, top sheets, side drawers, snap points, dragging, backdrop dismissal, and both controlled and imperative usage.

    Basic Usage

    Start with SheetRoot, SheetView, SheetBackdrop, and SheetContent. Put the visual surface on SheetContent, then use the backdrop and drag gestures for natural dismissal.

    Examples

    Auto Height

    Use the fit snap point when the panel height should follow its content. This works well for menus, short forms, and content whose height is not known ahead of time.

    Controlled

    Use show with onShowChange when the open state belongs to the page. This is the right model when other UI, analytics, or navigation logic must stay in sync with the sheet.

    Side

    Use side to choose whether Sheet behaves like a bottom panel, top panel, or drawer. Prefer start and end for layouts that should follow RTL, and left or right when the physical edge must stay fixed.

    Imperative

    Use SheetRootRef when a parent needs to command the sheet directly. Methods such as open, close, snapTo, expand, and collapse are useful for toolbar actions and coordinated multi-step flows.

    Structure

    <SheetRoot>
      <SheetView>
        <SheetBackdrop />
        <SheetContent>
          <SheetHandle />
        </SheetContent>
      </SheetView>
    </SheetRoot>

    Component API

    SheetRoot

    The root component of the Sheet, containing all of its child components.

    childreniOSAndroidHarmony
    TypeReactNode
    children
    claimedGestureAngles
    Type[number, number][]
    Angle ranges (in degrees) where gestures should be claimed by the Sheet. Each entry is [minAngle, maxAngle]. Gestures within these angle ranges will trigger sheet movement, while gestures outside these ranges are passed through. see https://lynxjs.org/api/elements/built-in/view#consume-slide-event for more
    classNameiOSAndroidHarmony
    Typestring
    className
    defaultShowiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Whether the sheet should be shown by default. Use this for uncontrolled mode.
    dismissThreshold
    Typenumber
    The threshold to dismiss the Sheet.
    dragDisabled
    Typeboolean
    Whether to disable dragging on the Sheet.
    enableDragToClose
    Typeboolean
    Whether to enable dragging to close the Sheet. If true, dragging from the lowest snap point toward the closed edge will move the sheet linearly and allow dismissal. If false, dragging toward the closed edge will trigger rubber band effect and snap back. A fling toward the open edge returns to an open snap point, even from the dismiss zone.
    enableRTL
    Typeboolean·Defaultfalse
    Whether the Sheet should use RTL direction. This sets the Sheet viewport direction to rtl by default and resolves logical drawer sides in RTL mode. When false, start means left and end means right. When true, start means right and end means left. Physical left and right sides are not affected by enableRTL.
    forceMountiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Mount the sheet and render its content even when not shown. The sheet remains in closed state.
    handleOnly
    Typeboolean
    Whether to restrict dragging to the handle only.
    initialSnap
    Typenumber
    The initial snap point index.
    onCloseiOSAndroidHarmony
    Type() => void
    Called when the sheet has fully closed and any exit animation has finished.
    onOpeniOSAndroidHarmony
    Type() => void
    Called when the sheet has fully opened and any enter animation has finished.
    onShowChangeiOSAndroidHarmony
    Type(open: boolean) => void
    Called when the sheet's visibility is about to change (e.g., backdrop click, swipe dismiss, close button). In controlled mode, use this to update your state. In uncontrolled mode, this is optional.
    onSnapChange
    Type(index: number, value: number) => void
    Callback when the snap point changes. value is the resolved snap point in pixels.
    rubberBand
    Typenumber | boolean | {coeff?: number, max?: number}
    The rubber band effect configuration. By default, rubber band over-drag is enabled for vertical sheets (top / bottom) and disabled for horizontal drawers (left / right / start / end). If true, enables default rubber band effect (coefficient 0.5). If false, disables rubber band effect. If number, enables rubber band effect with the specified coefficient. If object, allows specifying coefficient and max distance.
    screenHeight
    Typenumber
    The height of the Sheet container (screen height). Used in vertical sheet mode (top / bottom) for percentage snap points and dismissal calculations.
    screenWidth
    Typenumber
    The width of the Sheet container (screen width). Used in horizontal drawer mode (left / right / start / end) for percentage snap points and dismissal calculations.
    showiOSAndroidHarmony
    Typeboolean
    Whether to show the sheet. If this property is set, the sheet will be in controlled mode, meaning the defaultShow property will have no effect. You must control the visibility by updating this prop based on user interactions.
    side
    TypeSheetSide·Default'bottom'
    The side from which the sheet enters. bottom preserves the existing bottom-sheet behavior. top provides top-sheet behavior. left and right provide physical drawer behavior. start and end provide logical drawer behavior and resolve against enableRTL.
    snapPoints
    Type(string | number)[]·Default['fit']
    The snap points of the Sheet. Can be pixel numbers, percentages, or 'fit'. - Numbers are treated as pixel values - Percentages (e.g., '50%') are relative to screen height for top / bottom, and relative to screen width for left / right / start / end - 'fit' dynamically resolves to the measured content height for top / bottom, and the measured content width for left / right / start / end
    styleiOSAndroidHarmony
    TypeCSSProperties
    style

    SheetBackdrop

    The backdrop mask of the Sheet.

    childreniOSAndroidHarmony
    TypeReactNode
    children
    classNameiOSAndroidHarmony
    Typestring
    className
    clickToCloseiOSAndroidHarmony
    Typeboolean·Defaulttrue
    Whether to close the Sheet when the overlay is clicked.
    onClickiOSAndroidHarmony
    Type() => void
    Triggered when the backdrop is clicked.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style

    SheetView

    The view container of the Sheet. Can be x-overlay-ng or view. Controls the Sheet's overlay layer and stacking order.

    childreniOSAndroidHarmony
    TypeReactNode
    children
    classNameiOSAndroidHarmony
    Typestring
    className
    containeriOSAndroidHarmony
    Type'spark' | 'bullet' | 'bulletPopup' | (string & {})
    If you want to render the Sheet outside of the LynxView, set this property. The values 'spark', 'bullet', and 'bulletPopup' are names of native containers. For example, on TikTok it should be 'spark', and on Douyin it should be 'bullet'. On iOS, this prop can also be any native view controller that should host the Sheet. Use it to place the Sheet in the correct native layer.
    idiOSAndroidHarmony
    Typestring
    id
    nativePropsiOSAndroidHarmony
    TypeOverlayViewProps | ViewProps
    Additional props that will be passed through to the underlying element.
    overlayLeveliOSAndroidHarmony
    Type2 | 1 | 3 | 4
    Only works when the 'container' is set to non-empty string. Adjust nearby elements display level.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style

    SheetContent

    The main content of the Sheet.

    childreniOSAndroidHarmony
    TypeReactNode
    children
    classNameiOSAndroidHarmony
    Typestring
    className
    enterAnimation
    TypeSheetTransition
    The enter animation configuration.
    exitAnimation
    TypeSheetTransition
    The exit animation configuration.
    innerClassNameiOSAndroidHarmony
    Typestring
    CSS class name for the inner layer. Use this for content layout and sizing styles. In horizontal drawer mode, the drawer width should be set here so 'fit' can resolve from the measured drawer width.
    innerStyleiOSAndroidHarmony
    TypeCSSProperties
    Inline styles for the inner layer. Use this for content layout and sizing styles. Note: Visual styles (background, borderRadius, etc.) should be set via the main style prop which applies to the moving surface layer. In horizontal drawer mode, set drawer width here so 'fit' can resolve from the measured drawer width.
    snapAnimation
    TypeSheetTransition
    The transition configuration for the Sheet snap animation.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style

    SheetHandle

    The handle of the Sheet.

    childreniOSAndroidHarmony
    TypeReactNode
    children
    classNameiOSAndroidHarmony
    Typestring
    className
    styleiOSAndroidHarmony
    TypeCSSProperties
    style

    SheetRootRef

    close
    Type(opts?: {animate?: boolean, snapAnimation?: SheetTransition}) => void
    collapse
    Type(opts?: {animate?: boolean, snapAnimation?: SheetTransition}) => void
    expand
    Type(opts?: {animate?: boolean, snapAnimation?: SheetTransition}) => void
    open
    Type(opts?: {animate?: boolean, snapAnimation?: SheetTransition}) => void
    snapTo
    Type(index: number, opts?: {animate?: boolean, snapAnimation?: SheetTransition}) => void

    Supporting Types

    SheetSide

    SheetSide
    Typetop | bottom | left | right | start | end

    SheetTransition

    SheetTransition
    TypeSheetTransitionSpring | SheetTransitionTween

    SheetTransitionSpring

    damping
    Typenumber
    mass
    Typenumber
    stiffness
    Typenumber
    type
    Type"spring"

    SheetTransitionTween

    duration
    Typenumber
    ease
    Type(t: number) => number
    type
    Type"tween"
    Except as otherwise noted, this work is licensed under a Creative Commons Attribution 4.0 International License, and code samples are licensed under the Apache License 2.0.