<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.
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>
API
SheetRoot
The root component of the Sheet, containing all of its child components.
Typeundefined[]
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
Typeboolean·Defaultfalse
Whether the sheet should be shown by default. Use this for uncontrolled mode.
Typenumber
The threshold to dismiss the Sheet.
Typeboolean
Whether to disable dragging on the Sheet.
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.
Typeboolean·Defaultfalse
Whether logical drawer sides should resolve 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.
Typeboolean·Defaultfalse
Mount the sheet and render its content even when not shown. The sheet remains in closed state.
Typeboolean
Whether to restrict dragging to the handle only.
Typenumber
The initial snap point index.
Type() => void
Called when the sheet has fully closed and any exit animation has finished.
Type() => void
Called when the sheet has fully opened and any enter animation has finished.
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.
Type(index: number, value: number) => void
Callback when the snap point changes.
value is the resolved snap point in pixels.
Typenumber | boolean | [object Object]
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.
Typenumber
The height of the Sheet container (screen height).
Used in vertical sheet mode (top / bottom) for percentage snap points
and dismissal calculations.
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.
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.
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.
Typeundefined[]·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
SheetBackdrop
The backdrop mask of the Sheet.
Typeboolean·Defaulttrue
Whether to close the Sheet when the overlay is clicked.
Type() => void
Triggered when the backdrop is clicked.
SheetView
The view container of the Sheet. Can be x-overlay-ng or view.
Controls the Sheet's overlay layer and stacking order.
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.
TypeOverlayViewProps | ViewProps
Additional props that will be passed through to the underlying element.
Type2 | 1 | 3 | 4
Only works when the 'container' is set to non-empty string. Adjust nearby elements display level.
SheetContent
The main content of the Sheet.
TypeSheetTransition
The enter animation configuration.
TypeSheetTransition
The exit animation configuration.
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.
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.
TypeSheetTransition
The transition configuration for the Sheet snap animation.
