> For AI agents: the complete documentation index is available at /next/llms.txt, the full documentation bundle is available at /next/llms-full.txt.

# 

# 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](https://github.com/lynx-family/lynx-ui/tree/main/packages/lynx-ui-sheet) 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.


**This is an example below: lynx-ui-sheet**

**Entry:** `Basic`
**Bundle:** `dist/SheetBasic.lynx.bundle` | Web: `dist/SheetBasic.web.bundle`

```tsx {26-56}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.
import { root, useRef } from '@lynx-js/react'

import {
  SheetBackdrop,
  SheetContent,
  SheetHandle,
  SheetRoot,
  SheetView,
} from '@lynx-js/lynx-ui'
import type { SheetRootRef } from '@lynx-js/lynx-ui'

import { ActionButton, TriggerButton } from '../shared/index.js'
import './index.css'

const snapPoints = ['50%']

function App() {
  const sheetRef = useRef<SheetRootRef>(null)

  return (
    <view className='demo-container lunaris-dark'>
      <text className='title-text'>Basic Sheet</text>
      <TriggerButton
        onClick={() => sheetRef.current?.open()}
        text='Open Sheet'
      />
      <SheetRoot
        ref={sheetRef}
        snapPoints={snapPoints}
        initialSnap={0}
        onOpen={() => console.log('Sheet opened')}
        onClose={() => console.log('Sheet closed')}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <SheetContent
            className='sheet-content'
            innerClassName='sheet-inner-content'
          >
            <SheetHandle className='sheet-handle' />
            <view className='control-panel'>
              <text className='header-text'>Basic Sheet</text>
              <text className='info-text'>
                Simple uncontrolled sheet. Drag or tap backdrop to dismiss.
              </text>
              <ActionButton
                onClick={() => sheetRef.current?.close()}
                text='Close'
              />
            </view>
          </SheetContent>
        </SheetView>
      </SheetRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



## 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.


**This is an example below: lynx-ui-sheet**

**Entry:** `AutoHeight`
**Bundle:** `dist/SheetAutoHeight.lynx.bundle` | Web: `dist/SheetAutoHeight.web.bundle`

```tsx {18-19,48-50,57-72}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.
import { root, useRef } from '@lynx-js/react'

import {
  SheetBackdrop,
  SheetContent,
  SheetHandle,
  SheetRoot,
  SheetView,
} from '@lynx-js/lynx-ui'
import type { SheetRootRef } from '@lynx-js/lynx-ui'

import { ActionButton, TriggerButton } from '../shared/index.js'
import './index.css'

const fitSnapPoints = ['fit']
const fitAndPercentSnapPoints = ['fit', '80%']
const claimedGestureAngles: [number, number][] = [[-135, -45], [45, 135]]

const longText =
  'The Sheet component supports autoHeight mode, where the height is dynamically calculated based on its content. '
    .repeat(10)

function App() {
  const fitSheetRef = useRef<SheetRootRef>(null)
  const fitAndPercentSheetRef = useRef<SheetRootRef>(null)

  return (
    <view className='demo-container lunaris-dark'>
      <text className='title-text'>Sheet Auto Height</text>

      <view className='button-group'>
        <TriggerButton
          onClick={() => fitSheetRef.current?.open()}
          text='Open Fit Sheet'
        />
        <TriggerButton
          onClick={() => fitAndPercentSheetRef.current?.open()}
          text='Open Fit + 80% Sheet'
        />
      </view>

      <SheetRoot
        ref={fitSheetRef}
        onShowChange={(show) => {
          console.log('fit show change', show)
        }}
        onOpen={() => {
          console.log('fit open change')
        }}
        onClose={() => {
          console.log('fit close change')
        }}
        snapPoints={fitSnapPoints}
        initialSnap={0}
        claimedGestureAngles={claimedGestureAngles}
        onSnapChange={(snapIndex, snapValue) => {
          console.log('fit snap change', snapIndex, snapValue)
        }}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' />
          <SheetContent
            className='sheet-content'
            innerClassName='sheet-inner-content'
          >
            <SheetHandle className='sheet-handle' />
            <view className='control-panel'>
              <text className='header-text'>
                Fit Sheet with Long Content
              </text>
              <text className='info-text'>snapPoints=["fit"]</text>
              <text className='info-text'>{longText}</text>
              <ActionButton
                onClick={() => fitSheetRef.current?.close()}
                text='Close via Ref'
              />
            </view>
          </SheetContent>
        </SheetView>
      </SheetRoot>

      <SheetRoot
        ref={fitAndPercentSheetRef}
        snapPoints={fitAndPercentSnapPoints}
        initialSnap={0}
        claimedGestureAngles={claimedGestureAngles}
        onSnapChange={(snapIndex, snapValue) => {
          console.log('fit + 80% snap change', snapIndex, snapValue)
        }}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' />
          <SheetContent
            className='sheet-content'
            innerClassName='sheet-inner-content'
          >
            <SheetHandle className='sheet-handle' />
            <view className='control-panel'>
              <text className='header-text'>
                Fit Sheet with Percent Snap
              </text>
              <text className='info-text'>snapPoints=["fit", "80%"]</text>
              <text className='info-text'>
                The fit snap uses measured content height, while 80% resolves
                against the viewport height.
              </text>
              <ActionButton
                onClick={() => fitAndPercentSheetRef.current?.snapTo(0)}
                text='Snap to fit'
              />
              <ActionButton
                onClick={() => fitAndPercentSheetRef.current?.snapTo(1)}
                text='Snap to 80%'
              />
              <ActionButton
                onClick={() => fitAndPercentSheetRef.current?.close()}
                text='Close via Ref'
              />
            </view>
          </SheetContent>
        </SheetView>
      </SheetRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



### 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.


**This is an example below: lynx-ui-sheet**

**Entry:** `Controlled`
**Bundle:** `dist/SheetControlled.lynx.bundle` | Web: `dist/SheetControlled.web.bundle`

```tsx {23-24,32-42,36-54}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.
import { root, useRef, useState } from '@lynx-js/react'

import {
  SheetBackdrop,
  SheetContent,
  SheetHandle,
  SheetRoot,
  SheetView,
} from '@lynx-js/lynx-ui'
import type { SheetRootRef } from '@lynx-js/lynx-ui'

import { ActionButton, SnapButton, TriggerButton } from '../shared/index.js'

import './index.css'

const snapPoints = ['40%', '80%']

function App() {
  const sheetRef = useRef<SheetRootRef>(null)
  // Fully controlled state - parent manages show/hide
  const [show, setShow] = useState(false)

  return (
    <view className='demo-container lunaris-dark'>
      <text className='title-text'>Controlled Sheet</text>
      <text className='subtitle-text'>
        show: {show ? 'true' : 'false'}
      </text>
      <TriggerButton
        onClick={() => setShow(s => !s)}
        text={show ? 'Opened' : 'Open (setShow(true))'}
      />
      <SheetRoot
        ref={sheetRef}
        show={show}
        onShowChange={(newShow) => {
          console.log('onShowChange:', newShow)
          setShow(newShow)
        }}
        onOpen={() => {
          console.log('onOpen - sheet fully opened')
        }}
        onClose={() => {
          console.log('onClose - sheet fully closed')
        }}
        snapPoints={snapPoints}
        initialSnap={0}
        onSnapChange={(snapIndex, snapValue) => {
          console.log('onSnapChange:', snapIndex, snapValue)
        }}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <SheetContent
            className='sheet-content'
            innerClassName='sheet-inner-content'
            snapAnimation={{ type: 'spring', stiffness: 300, damping: 25 }}
          >
            <SheetHandle className='sheet-handle' />
            <view className='control-panel'>
              <text className='header-text'>
                Controlled Sheet
              </text>
              <text className='info-text'>
                The parent component manages the `show` state. Backdrop taps and
                gestures trigger `onShowChange`.
              </text>
              <view className='button-group'>
                <SnapButton
                  onClick={() => sheetRef.current?.snapTo(0)}
                  text='Snap to 40%'
                />
                <SnapButton
                  onClick={() => sheetRef.current?.snapTo(1)}
                  text='Snap to 80%'
                />
              </view>

              <ActionButton
                onClick={() => setShow(false)}
                text='Close (setShow(false))'
              />
            </view>
          </SheetContent>
        </SheetView>
      </SheetRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



### 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.


**This is an example below: lynx-ui-sheet**

**Entry:** `Directional`
**Bundle:** `dist/SheetDirectional.lynx.bundle` | Web: `dist/SheetDirectional.web.bundle`

```tsx {95-119,134-139,173-204}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.
import { root, useRef } from '@lynx-js/react'

import {
  SheetBackdrop,
  SheetContent,
  SheetHandle,
  SheetRoot,
  SheetView,
} from '@lynx-js/lynx-ui'
import type { SheetRootRef } from '@lynx-js/lynx-ui'

import { ActionButton, TriggerButton } from '../shared/index.js'

import './index.css'

function DrawerSection(
  props: {
    title: string
    description: string
    note: string
    close: () => void
    surfaceClassName: string
    innerClassName: string
  },
) {
  const {
    title,
    description,
    note,
    close,
    surfaceClassName,
    innerClassName,
  } = props

  return (
    <SheetContent
      className={surfaceClassName}
      innerClassName={innerClassName}
    >
      <view className='drawer-panel'>
        <text className='header-text'>{title}</text>
        <text className='info-text'>{description}</text>
        <text className='info-text'>{note}</text>
        <ActionButton onClick={close} text='Close Drawer' />
      </view>
    </SheetContent>
  )
}

function App() {
  const leftDrawerRef = useRef<SheetRootRef>(null)
  const rightDrawerRef = useRef<SheetRootRef>(null)
  const startDrawerRef = useRef<SheetRootRef>(null)
  const endDrawerRef = useRef<SheetRootRef>(null)
  const rtlLeftDrawerRef = useRef<SheetRootRef>(null)
  const rtlRightDrawerRef = useRef<SheetRootRef>(null)
  const topSheetRef = useRef<SheetRootRef>(null)
  const bottomSheetRef = useRef<SheetRootRef>(null)

  return (
    <view className='demo-container lunaris-dark'>
      <text className='title-text'>Directional Sheet</text>
      <text className='subtitle-text'>
        Left and right are physical sides. Start and end are logical sides that
        can flip with enableRTL.
      </text>
      <view className='button-group'>
        <TriggerButton
          onClick={() => leftDrawerRef.current?.open()}
          text='Open Left Drawer'
        />
        <TriggerButton
          onClick={() => rightDrawerRef.current?.open()}
          text='Open Right Drawer'
        />
        <TriggerButton
          onClick={() => startDrawerRef.current?.open()}
          text='Open Start Drawer'
        />
        <TriggerButton
          onClick={() => endDrawerRef.current?.open()}
          text='Open End Drawer'
        />
        <TriggerButton
          onClick={() => rtlLeftDrawerRef.current?.open()}
          text='Open RTL Left Drawer'
        />
        <TriggerButton
          onClick={() => rtlRightDrawerRef.current?.open()}
          text='Open RTL Right Drawer'
        />
        <TriggerButton
          onClick={() => topSheetRef.current?.open()}
          text='Open Top Sheet'
        />
        <TriggerButton
          onClick={() => bottomSheetRef.current?.open()}
          text='Open Bottom Sheet'
        />
      </view>

      <SheetRoot
        ref={leftDrawerRef}
        side='left'
        snapPoints={['fit']}
        initialSnap={0}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <DrawerSection
            title='Left Drawer'
            description='This drawer uses side="left" with snapPoints=["fit"].'
            note='Use physical sides when the panel should stay on that edge in both LTR and RTL.'
            close={() => leftDrawerRef.current?.close()}
            surfaceClassName='drawer-content drawer-content-left'
            innerClassName='drawer-inner-content drawer-inner-content-fit'
          />
        </SheetView>
      </SheetRoot>

      <SheetRoot
        ref={rightDrawerRef}
        side='right'
        snapPoints={['72%']}
        initialSnap={0}
        rubberBand={true}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <DrawerSection
            title='Right Drawer'
            description='This drawer uses side="right" with a percentage snap point.'
            note='The 72% snap point resolves against viewport width instead of viewport height.'
            close={() => rightDrawerRef.current?.close()}
            surfaceClassName='drawer-content drawer-content-right'
            innerClassName='drawer-inner-content drawer-inner-content-percent'
          />
        </SheetView>
      </SheetRoot>

      <SheetRoot
        ref={startDrawerRef}
        side='start'
        enableRTL={true}
        snapPoints={['fit']}
        initialSnap={0}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <DrawerSection
            title='Start Drawer'
            description='This drawer uses side="start" with snapPoints=["fit"].'
            note='This example sets enableRTL, so start resolves to right. Disable it to make start resolve to left.'
            close={() => startDrawerRef.current?.close()}
            surfaceClassName='drawer-content drawer-content-right'
            innerClassName='drawer-inner-content drawer-inner-content-fit'
          />
        </SheetView>
      </SheetRoot>

      <SheetRoot
        ref={endDrawerRef}
        side='end'
        snapPoints={['72%']}
        initialSnap={0}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <DrawerSection
            title='End Drawer'
            description='This drawer uses side="end" with a percentage snap point.'
            note='Without enableRTL, end resolves to right. Turn enableRTL on to make end resolve to left.'
            close={() => endDrawerRef.current?.close()}
            surfaceClassName='drawer-content drawer-content-right'
            innerClassName='drawer-inner-content drawer-inner-content-percent'
          />
        </SheetView>
      </SheetRoot>

      <SheetRoot
        ref={rtlLeftDrawerRef}
        side='left'
        enableRTL={true}
        snapPoints={['fit']}
        initialSnap={0}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <DrawerSection
            title='RTL Left Drawer'
            description='This drawer uses side="left" with enableRTL.'
            note='Physical left stays left, while the Sheet viewport direction becomes RTL.'
            close={() => rtlLeftDrawerRef.current?.close()}
            surfaceClassName='drawer-content drawer-content-left'
            innerClassName='drawer-inner-content drawer-inner-content-fit'
          />
        </SheetView>
      </SheetRoot>

      <SheetRoot
        ref={rtlRightDrawerRef}
        side='right'
        enableRTL={true}
        snapPoints={['72%']}
        initialSnap={0}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <DrawerSection
            title='RTL Right Drawer'
            description='This drawer uses side="right" with enableRTL.'
            note='Physical right stays right, while the Sheet viewport direction becomes RTL.'
            close={() => rtlRightDrawerRef.current?.close()}
            surfaceClassName='drawer-content drawer-content-right'
            innerClassName='drawer-inner-content drawer-inner-content-percent'
          />
        </SheetView>
      </SheetRoot>

      <SheetRoot
        ref={topSheetRef}
        side='top'
        snapPoints={['fit']}
        initialSnap={0}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <SheetContent
            className='top-sheet-shell'
            innerClassName='top-sheet-content'
          >
            <view className='top-sheet-panel'>
              <text className='header-text'>Top Sheet</text>
              <text className='info-text'>
                This sheet uses side="top". Its fit snap point resolves from
                measured height.
              </text>
              <ActionButton
                onClick={() => topSheetRef.current?.close()}
                text='Close Top Sheet'
              />
            </view>
          </SheetContent>
        </SheetView>
      </SheetRoot>

      <SheetRoot
        ref={bottomSheetRef}
        side='bottom'
        snapPoints={['fit']}
        initialSnap={0}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <SheetContent
            className='bottom-sheet-shell'
            innerClassName='bottom-sheet-content'
          >
            <SheetHandle className='bottom-sheet-handle' />
            <view className='bottom-sheet-panel'>
              <text className='header-text'>Bottom Sheet</text>
              <text className='info-text'>
                This sheet uses the default bottom side. Its fit snap point
                resolves from measured height.
              </text>
              <ActionButton
                onClick={() => bottomSheetRef.current?.close()}
                text='Close Bottom Sheet'
              />
            </view>
          </SheetContent>
        </SheetView>
      </SheetRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



### 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.


**This is an example below: lynx-ui-sheet**

**Entry:** `Imperative`
**Bundle:** `dist/SheetImperative.lynx.bundle` | Web: `dist/SheetImperative.web.bundle`

```tsx {22,28-34,63-89}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.
import { root, useRef } from '@lynx-js/react'

import {
  SheetBackdrop,
  SheetContent,
  SheetHandle,
  SheetRoot,
  SheetView,
} from '@lynx-js/lynx-ui'
import type { SheetRootRef } from '@lynx-js/lynx-ui'

import { ActionButton, SnapButton, TriggerButton } from '../shared/index.js'

import './index.css'

const snapPoints = ['40%', '60%', '90%']

function App() {
  const sheetRef = useRef<SheetRootRef>(null)

  return (
    <view className='demo-container lunaris-dark'>
      <text className='title-text'>Imperative Sheet</text>

      <TriggerButton
        text='Open Sheet (via ref)'
        onClick={() => sheetRef.current?.open()}
      />

      <SheetRoot
        ref={sheetRef}
        onShowChange={(show) => {
          console.log('show change', show)
        }}
        onOpen={() => {
          console.log('open change')
        }}
        onClose={() => {
          console.log('close change')
        }}
        snapPoints={snapPoints}
        initialSnap={0}
        onSnapChange={(snapIndex, snapValue) => {
          console.log(snapIndex, snapValue)
        }}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <SheetContent
            className='sheet-content'
            innerClassName='sheet-inner-content'
            snapAnimation={{ type: 'spring', stiffness: 300, damping: 20 }}
          >
            <SheetHandle className='sheet-handle' />
            <view className='control-panel'>
              <text className='header-text'>
                Imperative Methods
              </text>

              <view className='button-group'>
                <SnapButton
                  text='40%'
                  onClick={() => sheetRef.current?.snapTo(0)}
                />
                <SnapButton
                  text='60%'
                  onClick={() => sheetRef.current?.snapTo(1)}
                />
                <SnapButton
                  text='90%'
                  onClick={() => sheetRef.current?.snapTo(2)}
                />
                <SnapButton
                  text='Expand (Max)'
                  onClick={() => sheetRef.current?.expand()}
                />
                <SnapButton
                  text='Collapse (Min)'
                  onClick={() => sheetRef.current?.collapse()}
                />
              </view>

              <ActionButton
                text='Close'
                onClick={() => sheetRef.current?.close()}
              />
            </view>
          </SheetContent>
        </SheetView>
      </SheetRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



## Structure

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

## Component API \{#api}

### SheetRoot \{#api-sheet-root}

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


### SheetBackdrop \{#api-sheet-backdrop}

The backdrop mask of the Sheet.


### SheetView \{#api-sheet-view}

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


### SheetContent \{#api-sheet-content}

The main content of the Sheet.


### SheetHandle \{#api-sheet-handle}

The handle of the Sheet.


### SheetRootRef \{#api-sheet-root-ref}


## Supporting Types \{#api-supporting-types}

### SheetSide \{#api-supporting-types-sheet-side}


### SheetTransition \{#api-supporting-types-sheet-transition}


### SheetTransitionSpring \{#api-supporting-types-sheet-transition-spring}


### SheetTransitionTween \{#api-supporting-types-sheet-transition-tween}

