React Spring Bottom Sheet

A draggable bottom sheet for React 19, with dialog semantics, focus management, snap points, and scroll-aware gestures. Use it for filters, account actions, or details that should stay close to the page the user is working on.

This is an independently maintained continuation of the original react-spring-bottom-sheet. Version 5 uses a redesigned compound API; existing applications need to follow the migration guide.

Live docs · Live demo · Migration from the original · API reference · npm

When to use it

Choose a sheet when the interaction benefits from dragging between heights or sharing space with the page. Modal sheets contain focus and isolate background content; modal={false} supports persistent panels such as map details. Named snap points can be content-sized, pixel heights, or viewport percentages.

For a simple dialog with no dragging or snap behavior, a native <dialog> or an existing dialog component may be enough. This version requires React 19 and current evergreen browsers; it is not a drop-in replacement for version 4.

Install

In an application with React 19 and React DOM 19:

npm install @nipe-solutions/react-spring-bottom-sheet

Quick start

Import the complete default stylesheet once. In a Next.js App Router application, put interactive sheet components behind a client boundary and import the stylesheet from the location your application uses for global CSS.

'use client'

import { Sheet } from '@nipe-solutions/react-spring-bottom-sheet'
import '@nipe-solutions/react-spring-bottom-sheet/styles.css'

export function AccountActions() {
  return (
    <Sheet.Root snapPoints={[{ id: 'content', value: 'content' }]}>
      <Sheet.Trigger>Open account actions</Sheet.Trigger>
      <Sheet.Portal>
        <Sheet.Backdrop />
        <Sheet.Viewport>
          <Sheet.Content>
            <Sheet.Handle />
            <Sheet.Title>Account actions</Sheet.Title>
            <Sheet.Description>
              Choose what you want to do next.
            </Sheet.Description>
            <Sheet.Close>Done</Sheet.Close>
          </Sheet.Content>
        </Sheet.Viewport>
      </Sheet.Portal>
    </Sheet.Root>
  )
}

The example manages its own open state. To connect it to application state, use open and onOpenChange together. Keep Sheet.Title in the content so the dialog has an accessible name; Sheet.Description supplies optional context.

See component anatomy, state, and the examples for controlled sheets, forms, and multiple snap points.

Why version 5

Compound components let you place actions, scroll regions, and surrounding content while the library owns gestures, motion, and modal coordination. BottomSheet provides the common structure as a convenience component. The mechanical stylesheet and optional theme have separate entry points, so you can keep the behavior while supplying your own design. Read the accessibility guide for dialog naming, focus, and non-modal behavior.

Styles

• /styles.css includes required mechanics and the default theme.
• /core.css includes mechanics only and is required for every sheet.
• /theme.css includes the optional visual theme and token defaults.
• /tokens.css exposes the default token declarations separately.

Use /styles.css for the example above. For your own theme, import /core.css and supply application CSS; omitting the mechanical stylesheet breaks the positioning and interaction contract.

All library-owned classes and custom properties use the rsbs namespace. Mechanical selectors use low specificity so an application can replace the visual design with ordinary CSS and without !important.

Support

• React 19
• Node.js 24 LTS for development, CI, and releases
• Current evergreen Chromium, Firefox, and WebKit browsers
• TypeScript declarations, ESM, and CommonJS package entry points

Gesture, dialog, focus, and styling behavior are covered by repository tests, including automated browser scenarios. Validate the sheet inside your own scroll containers, overlay stack, and target devices. A custom portal container must establish the size and clipping boundary the sheet should fill; see portals and layering.

Migrating from the original package

Move from react-spring-bottom-sheet to @nipe-solutions/react-spring-bottom-sheet with the dedicated migration page and the detailed repository guide. Props, refs, callbacks, snap points, and CSS selectors changed in version 5.

For development and contributions, read CONTRIBUTING.md.

Project lineage

The project was created by Cody Olsen in stipsan/react-spring-bottom-sheet and later maintained by Jasmine GH in JasGH/react-spring-bottom-sheet. This fork remains in that GitHub fork network and is independently maintained by NIPE Solutions. The original authorship and MIT license notices are preserved.

License

MIT. See third-party notices for preserved dependency notices.