Skip to content

docs: improve adoption guidance and verified quick start #65

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Cylop merged 1 commit into from
Oct 1, 2026
Merged

docs: improve adoption guidance and verified quick start #65

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 66 additions & 29 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,43 +5,46 @@
[![MIT license](https://img.shields.io/badge/license-MIT-0f766e.svg)](LICENSE)
[![React 19](https://img.shields.io/badge/React-19-087ea4.svg?logo=react)](https://react.dev/)

Accessible, composable bottom sheets for React 19. An independently maintained continuation of the original `react-spring-bottom-sheet`, rebuilt with compound components, explicit styling contracts, and current-browser verification.
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.

[Live docs](https://react-spring-bottom-sheet.nipesolutions.com) · [Live demo](https://react-spring-bottom-sheet.nipesolutions.com/examples) · [Migration from the original](https://react-spring-bottom-sheet.nipesolutions.com/migration-from-react-spring-bottom-sheet/) · [API reference](https://react-spring-bottom-sheet.nipesolutions.com/api) · [npm](https://www.npmjs.com/package/@nipe-solutions/react-spring-bottom-sheet)
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.

## Install
[Live docs](https://react-spring-bottom-sheet.nipesolutions.com) · [Live demo](https://react-spring-bottom-sheet.nipesolutions.com/examples) · [Migration from the original](https://react-spring-bottom-sheet.nipesolutions.com/migration-from-react-spring-bottom-sheet/) · [API reference](https://react-spring-bottom-sheet.nipesolutions.com/docs/api/) · [npm](https://www.npmjs.com/package/@nipe-solutions/react-spring-bottom-sheet)

```bash
npm install @nipe-solutions/react-spring-bottom-sheet
```
## When to use it

Import the complete default styling once from your application entry point:
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.

```ts
import '@nipe-solutions/react-spring-bottom-sheet/styles.css'
```
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.

## Why version 5
## Install

- Built for React 19 with accessible dialog and focus behavior backed by
explicit accessibility tests.
- Interruption-safe gestures and motion keep the sheet responsive through rapid
input and state changes.
- Replaceable styling contracts let applications own the visual design without
fighting library mechanics.
- Verified against current evergreen Chromium, Firefox, and WebKit browsers.
In an application with React 19 and React DOM 19:

## Migrating from the original package
```bash
npm install @nipe-solutions/react-spring-bottom-sheet
```

Move from `react-spring-bottom-sheet` to
`@nipe-solutions/react-spring-bottom-sheet` with the [dedicated migration
page](https://react-spring-bottom-sheet.nipesolutions.com/migration-from-react-spring-bottom-sheet/)
and the [detailed repository guide](docs/migration-v4-to-v5.md).
## Quick start

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

```tsx
'use client'

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

export function AccountActions() {
return (
Expand All @@ -65,7 +68,24 @@ export function AccountActions() {
}
```

`BottomSheet` is available as a convenience component for the common structure.
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](https://react-spring-bottom-sheet.nipesolutions.com/docs/anatomy/),
[state](https://react-spring-bottom-sheet.nipesolutions.com/docs/state/), and the
[examples](https://react-spring-bottom-sheet.nipesolutions.com/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](https://react-spring-bottom-sheet.nipesolutions.com/docs/accessibility/)
for dialog naming, focus, and non-modal behavior.

## Styles

Expand All @@ -74,6 +94,10 @@ export function AccountActions() {
- `/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`.
Expand All @@ -85,9 +109,21 @@ visual design with ordinary CSS and without `!important`.
- Current evergreen Chromium, Firefox, and WebKit browsers
- TypeScript declarations, ESM, and CommonJS package entry points

Read the [documentation](https://react-spring-bottom-sheet.nipesolutions.com),
the [migration guide](docs/migration-v4-to-v5.md), and the [contribution
guide](CONTRIBUTING.md).
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](https://react-spring-bottom-sheet.nipesolutions.com/docs/portals/).

## Migrating from the original package

Move from `react-spring-bottom-sheet` to
`@nipe-solutions/react-spring-bottom-sheet` with the [dedicated migration
page](https://react-spring-bottom-sheet.nipesolutions.com/migration-from-react-spring-bottom-sheet/)
and the [detailed repository guide](docs/migration-v4-to-v5.md). Props, refs,
callbacks, snap points, and CSS selectors changed in version 5.

For development and contributions, read [CONTRIBUTING.md](CONTRIBUTING.md).

## Project lineage

Expand All @@ -101,4 +137,5 @@ MIT license notices are preserved.

## License

MIT
[MIT](LICENSE). See [third-party notices](THIRD_PARTY_NOTICES.md) for preserved
dependency notices.
Loading