Installations
npm install react-spring-bottom-sheetDeveloper Guide
Typescript
Yes
Module System
CommonJS
Node Version
14.19.2
NPM Version
7.24.2
Score
90.5
Supply Chain
91.6
Quality
75.5
Maintenance
100
Vulnerability
100
License
Releases
Contributors
Unable to fetch Contributors
Languages
TypeScript (94.15%)
CSS (3.41%)
JavaScript (2.43%)
Love this project? Help keep it running — sponsor us today! 🚀
Developer
Download Statistics
Total Downloads
7,868,789
Last Day
16,034
Last Week
71,573
Last Month
333,379
Last Year
4,164,538
GitHub Statistics
985 Stars
242 Commits
139 Forks
7 Watching
23 Branches
8 Contributors
Bundle Size
146.00 kB
Minified
44.27 kB
Minified + Gzipped
Maintainers
Package Meta Information
Latest Version
3.4.1
Package Id
react-spring-bottom-sheet@3.4.1
Unpacked Size
347.64 kB
Size
92.28 kB
File Count
26
NPM Version
7.24.2
Node Version
14.19.2
Total Downloads
Cumulative downloads
Total Downloads
7,868,789
Last day
4.7%
16,034
Compared to previous day
Last week
-10.2%
71,573
Compared to previous week
Last month
-1.8%
333,379
Compared to previous month
Last year
75.1%
4,164,538
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
8
Peer Dependencies
1
Dev Dependencies
41
react-spring-bottom-sheet is built on top of react-spring and react-use-gesture. It busts the myth that accessibility and supporting keyboard navigation and screen readers are allegedly at odds with delightful, beautiful, and highly animated UIs. Every animation and transition use CSS custom properties instead of manipulating them directly, allowing complete control over the experience from CSS alone.
Installation
1npm i react-spring-bottom-sheet
Getting started
Basic usage
1import { useState } from 'react' 2import { BottomSheet } from 'react-spring-bottom-sheet' 3 4// if setting up the CSS is tricky, you can add this to your page somewhere: 5// <link rel="stylesheet" href="https://unpkg.com/react-spring-bottom-sheet/dist/style.css" crossorigin="anonymous"> 6import 'react-spring-bottom-sheet/dist/style.css' 7 8export default function Example() { 9 const [open, setOpen] = useState(false) 10 return ( 11 <> 12 <button onClick={() => setOpen(true)}>Open</button> 13 <BottomSheet open={open}>My awesome content here</BottomSheet> 14 </> 15 ) 16}
TypeScript
TS support is baked in, and if you're using the snapTo API use BottomSheetRef:
1import { useRef } from 'react' 2import { BottomSheet, BottomSheetRef } from 'react-spring-bottom-sheet' 3 4export default function Example() { 5 const sheetRef = useRef<BottomSheetRef>() 6 return ( 7 <BottomSheet open ref={sheetRef}> 8 <button 9 onClick={() => { 10 // Full typing for the arguments available in snapTo, yay!! 11 sheetRef.current.snapTo(({ maxHeight }) => maxHeight) 12 }} 13 > 14 Expand to full height 15 </button> 16 </BottomSheet> 17 ) 18}
Customizing the CSS
Using CSS Custom Properties
These are all the variables available to customize the look and feel when using the provided CSS.
1:root { 2 --rsbs-backdrop-bg: rgba(0, 0, 0, 0.6); 3 --rsbs-bg: #fff; 4 --rsbs-handle-bg: hsla(0, 0%, 0%, 0.14); 5 --rsbs-max-w: auto; 6 --rsbs-ml: env(safe-area-inset-left); 7 --rsbs-mr: env(safe-area-inset-right); 8 --rsbs-overlay-rounded: 16px; 9}
Custom CSS
It's recommended that you copy from style.css into your own project, and add this to your postcss.config.js setup (npm i postcss-custom-properties-fallback):
1module.exports = { 2 plugins: { 3 // Ensures the default variables are available 4 'postcss-custom-properties-fallback': { 5 importFrom: require.resolve('react-spring-bottom-sheet/defaults.json'), 6 }, 7 }, 8}
Demos
Basic
MVP example, showing what you get by implementing open, onDismiss and a single snap point always set to minHeight.
Snap points & overflow
A more elaborate example that showcases how snap points work. It also shows how it behaves if you want it to be open by default, and not closable. Notice how it responds if you resize the window, or scroll to the bottom and starts adjusting the height of the sheet without scrolling back up first.
Sticky header & footer
If you provide either a header or footer prop you'll enable the special behavior seen in this example. And they're not just sticky positioned, both areas support touch gestures.
Non-blocking overlay mode
In most cases you use a bottom sheet the same way you do with a dialog: you want it to overlay the page and block out distractions. But there are times when you want a bottom sheet but without it taking all the attention and overlaying the entire page. Providing blocking={false} helps this use case. By doing so you disable a couple of behaviors that are there for accessibility (focus-locking and more) that prevents a screen reader or a keyboard user from accidentally leaving the bottom sheet.
API
props
All props you provide, like className, style props or whatever else are spread onto the underlying <animated.div> instance, that you can style in your custom CSS using this selector: [data-rsbs-root].
Just note that the component is mounted in a @reach/portal at the bottom of <body>, and not in the DOM hierarchy you render it in.
open
Type: boolean
The only required prop, beyond children. And it's controlled, so if you don't set this to false then it's not possible to close the bottom sheet. It's worth knowing that the bottom sheet won't render anything but a @reach/dialog placeholder while open is false. Thus ensure your components behave as expected with being unmounted when the sheet closed. We can't really allow it to render and mount while in a closed/hidden position as there's no stable way of preventing keyboard users or screen readers from accidentally interacting with the closed bottom sheet as long as it's in the dom. This is especially problematic given it implements ARIA to optimize for a11y.
onDismiss
Type: () => void
Called when the user do something that signal they want to dismiss the sheet:
- hit the
esckey. - tap on the backdrop.
- swipes the sheet to the bottom of the viewport.
snapPoints
Type: (state) => number | number[]
This function should be pure as it's called often. You can choose to provide a single value or an array of values to customize the behavior. The state contains these values:
headerHeight– the current measured height of theheader.footerHeight– if afooterprop is provided then this is its height.height– the current height of the sheet.minHeight– the minimum height needed to avoid a scrollbar. If there's not enough height available to avoid it then this will be the same asmaxHeight.maxHeight– the maximum available height on the page, equivalent towindow.innerHeightand100vh.
1<BottomSheet 2 // Allow the user to select between minimun height to avoid a scrollbar, and fullscren 3 snapPoints={({ minHeight, maxHeight }) => [minHeight, maxHeight]} 4/>
defaultSnap
Type: number | (state) => number
Provide either a number, or a callback returning a number for the default position of the sheet when it opens.
state use the same arguments as snapPoints, plus two more values: snapPoints and lastSnap.
1<BottomSheet 2 // the first snap points height depends on the content, while the second one is equivalent to 60vh 3 snapPoints={({ minHeight, maxHeight }) => [minHeight, maxHeight / 0.6]} 4 // Opens the largest snap point by default, unless the user selected one previously 5 defaultSnap={({ lastSnap, snapPoints }) => 6 lastSnap ?? Math.max(...snapPoints) 7 } 8/>
header
Type: ReactNode
Supports the same value type as the children prop.
footer
Type: ReactNode
Supports the same value type as the children prop.
sibling
Type: ReactNode
Supports the same value type as the sibling prop. Renders the node as a child of [data-rsbs-root], but as a sibling to [data-rsbs-backdrop] and [data-rsbs-overlay]. This allows you to access the animation state and render elements on top of the bottom sheet, while being outside the overlay itself.
initialFocusRef
Type: React.Ref | false
A react ref to the element you want to get keyboard focus when opening. If not provided it's automatically selecting the first interactive element it finds. If set to false keyboard focus when opening is disabled.
blocking
Type: boolean
Enabled by default. Enables focus trapping of keyboard navigation, so you can't accidentally tab out of the bottom sheet and into the background. Also sets aria-hidden on the rest of the page to prevent Screen Readers from escaping as well.
scrollLocking
Type: boolean
iOS Safari, and some other mobile culprits, can be tricky if you're on a page that has scrolling overflow on document.body. Mobile browsers often prefer scrolling the page in these cases instead of letting you handle the touch interaction for UI such as the bottom sheet. Thus it's enabled by default. However it can be a bit agressive and can affect cases where you're putting a drag and drop element inside the bottom sheet. Such as <input type="range" /> and more. For these cases you can wrap them in a container and give them this data attribute [data-body-scroll-lock-ignore] to prevent intervention. Really handy if you're doing crazy stuff like putting mapbox-gl widgets inside bottom sheets.
expandOnContentDrag
Type: boolean
Disabled by default. By default, a user can expand the bottom sheet only by dragging a header or the overlay. This option enables expanding the bottom sheet on the content dragging.
Events
All events receive SpringEvent as their argument. The payload varies, but type is always present, which can be 'OPEN' | 'RESIZE' | 'SNAP' | 'CLOSE' depending on the scenario.
onSpringStart
Type: (event: SpringEvent) => void
Fired on: OPEN | RESIZE | SNAP | CLOSE.
If you need to delay the open animation until you're ready, perhaps you're loading some data and showing an inline spinner meanwhile. You can return a Promise or use an async function to make the bottom sheet wait for your work to finish before it starts the open transition.
1function Example() { 2 const [data, setData] = useState([]) 3 return ( 4 <BottomSheet 5 onSpringStart={async (event) => { 6 if (event.type === 'OPEN') { 7 // the bottom sheet gently waits 8 const data = await fetch(/* . . . */) 9 setData(data) 10 // and now we can proceed 11 } 12 }} 13 > 14 {data.map(/* . . . */)} 15 </BottomSheet> 16 ) 17}
onSpringCancel
Type: (event: SpringEvent) => void
Fired on: OPEN | CLOSE.
OPEN
In order to be as fluid and delightful as possible, the open state can be interrupted and redirected by the user without waiting for the open transition to complete. Maybe they changed their mind and decided to close the sheet because they tapped a button by mistake. This interruption can happen in a number of ways:
- the user swipes the sheet below the fold, triggering an
onDismissevent. - the user hits the
esckey, triggering anonDismissevent. - the parent component sets
opentofalsebefore finishing the animation. - a
RESIZEevent happens, like when an Android device shows its soft keyboard when an text editable input receives focus, as it changes the viewport height.
CLOSE
If the user reopens the sheet before it's done animating it'll trigger this event. Most importantly though it can fire if the bottom sheet is unmounted without enough time to clean animate itself out of the view before it rolls back things like body-scroll-lock, focus-trap and more. It'll still clean itself up even if React decides to be rude about it. But this also means that the event can fire after the component is unmounted, so you should avoid calling setState or similar without checking for the mounted status of your own wrapper component.
RESIZE
Type: { source: 'window' | 'maxheightprop' | 'element }
Fires whenever there's been a window resize event, or if the header, footer or content have changed its height in such a way that the valid snap points have changed.
source tells you what caused the resize. If the resize comes from a window.onresize event it's set to 'window'. 'maxheightprop' is if the maxHeight prop is used, and is fired whenever it changes. And 'element' is whenever the header, footer or content resize observers detect a change.
SNAP
Type: { source: 'dragging' | 'custom' | string }
Fired after dragging ends, or when calling ref.snapTo, and a transition to a valid snap point is happening.
source is 'dragging' if the snapping is responding to a drag gesture that just ended. And it's set to 'custom' when using ref.snapTo.
1function Example() { 2 return ( 3 <BottomSheet 4 onSpringStart={(event) => { 5 if (event.type === 'SNAP' && event.source === 'dragging') { 6 console.log('Starting a spring animation to user selected snap point') 7 } 8 }} 9 /> 10 ) 11}
When using snapTo it's possible to use a different source than 'custom':
1function Example() { 2 const sheetRef = useRef() 3 return ( 4 <BottomSheet 5 ref={sheetRef} 6 snapPoints={({ minHeight, maxHeight }) => [minHeight, maxHeight]} 7 onSpringEnd={(event) => { 8 if (event.type === 'SNAP' && event.source === 'snap-to-bottom') { 9 console.log( 10 'Just finished an imperativ transition to the bottom snap point' 11 ) 12 } 13 }} 14 > 15 <button 16 onClick={() => sheetRef.current.snapTo(0, { source: 'snap-to-bottom' })} 17 > 18 Snap to bottom 19 </button> 20 </BottomSheet> 21 ) 22}
onSpringEnd
Type: (event: SpringEvent) => void
Fired on: CLOSE.
The yin to onSpringStart's yang. It has the same characteristics. Including async/await and Promise support for delaying a transition. For CLOSE it gives you a hook into the step right after it has cleaned up everything after itself, and right before it unmounts itself. This can be useful if you have some logic that needs to perform some work before it's safe to unmount.
skipInitialTransition
Type: boolean
By default the initial open state is always transitioned to using an spring animation. Set skipInitialTransition to true and the initial open state will render as if it were the default state. Useful to avoid scenarios where the opening transition would be distracting.
ref
Methods available when setting a ref on the sheet:
1export default function Example() { 2 const sheetRef = React.useRef() 3 return <BottomSheet open ref={sheetRef} /> 4}
snapTo
Type: (numberOrCallback: number | (state => number)) => void, options?: {source?: string, velocity?: number}
Same signature as the defaultSnap prop, calling it will animate the sheet to the new snap point you return. You can either call it with a number, which is the height in px (it'll select the closest snap point that matches your value): ref.current.snapTo(200). Or:
1ref.current.snapTo(({ // Showing all the available props
2 headerHeight, footerHeight, height, minHeight, maxHeight, snapPoints, lastSnap }) =>
3 // Selecting the largest snap point, if you give it a number that doesn't match a snap point then it'll
4 // select whichever snap point is nearest the value you gave
5 Math.max(...snapPoints)
6)There's an optional second argument you can use to override event.source, as well as changing the velocity:
1ref.current.snapTo(({ snapPoints }) => Math.min(...snapPoints), { 2 // Each property is optional, here showing their default values 3 source: 'custom', 4 velocity: 1, 5})
height
Type: number
The current snap point, in other words the height, of the bottom sheet. This value is updated outside the React render cycle, for performance reasons.
1export default function Example() { 2 const sheetRef = React.useRef() 3 return ( 4 <BottomSheet 5 ref={sheetRef} 6 onSpringStart={() => { 7 console.log('Transition from:', sheetRef.current.height) 8 requestAnimationFrame(() => 9 console.log('Transition to:', sheetRef.current.height) 10 ) 11 }} 12 onSpringEnd={() => 13 console.log('Finished transition to:', sheetRef.current.height) 14 } 15 /> 16 ) 17}
Credits
- Play icon used on frame overlays: font-awesome
- Phone frame used in logo: Mono Devices 1.0
- iPhone frame used to wrap examples: iOS 14 UI Kit for Figma
No vulnerabilities found.
Reason
no dangerous workflow patterns detected
Reason
no binaries found in the repo
Reason
license file detected
Details
- Info: project has a license file: LICENSE:0
- Info: FSF or OSI recognized license: MIT License: LICENSE:0
Reason
packaging workflow detected
Details
- Info: Project packages its releases by way of GitHub Actions.: .github/workflows/publish.yml:24
Reason
dependency not pinned by hash detected -- score normalized to 1
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/nodejs.yml:23: update your workflow using https://app.stepsecurity.io/secureworkflow/stipsan/react-spring-bottom-sheet/nodejs.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/nodejs.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/stipsan/react-spring-bottom-sheet/nodejs.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:30: update your workflow using https://app.stepsecurity.io/secureworkflow/stipsan/react-spring-bottom-sheet/publish.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:32: update your workflow using https://app.stepsecurity.io/secureworkflow/stipsan/react-spring-bottom-sheet/publish.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/stipsan/react-spring-bottom-sheet/publish.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/stipsan/react-spring-bottom-sheet/publish.yml/main?enable=pin
- Warn: npmCommand not pinned by hash: .github/workflows/publish.yml:20
- Warn: npmCommand not pinned by hash: .github/workflows/publish.yml:37
- Info: 0 out of 6 GitHub-owned GitHubAction dependencies pinned
- Info: 1 out of 3 npmCommand dependencies pinned
Reason
Found 1/30 approved changesets -- score normalized to 0
Reason
0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Warn: no topLevel permission defined: .github/workflows/nodejs.yml:1
- Warn: no topLevel permission defined: .github/workflows/publish.yml:1
- Info: no jobLevel write permissions found
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
Project has not signed or included provenance with any releases.
Details
- Warn: release artifact v3.4.1 not signed: https://api.github.com/repos/stipsan/react-spring-bottom-sheet/releases/68392516
- Warn: release artifact v3.4.0 not signed: https://api.github.com/repos/stipsan/react-spring-bottom-sheet/releases/45065094
- Warn: release artifact v3.3.0 not signed: https://api.github.com/repos/stipsan/react-spring-bottom-sheet/releases/44661044
- Warn: release artifact v3.2.1 not signed: https://api.github.com/repos/stipsan/react-spring-bottom-sheet/releases/36921972
- Warn: release artifact v3.2.0 not signed: https://api.github.com/repos/stipsan/react-spring-bottom-sheet/releases/36739704
- Warn: release artifact v3.4.1 does not have provenance: https://api.github.com/repos/stipsan/react-spring-bottom-sheet/releases/68392516
- Warn: release artifact v3.4.0 does not have provenance: https://api.github.com/repos/stipsan/react-spring-bottom-sheet/releases/45065094
- Warn: release artifact v3.3.0 does not have provenance: https://api.github.com/repos/stipsan/react-spring-bottom-sheet/releases/44661044
- Warn: release artifact v3.2.1 does not have provenance: https://api.github.com/repos/stipsan/react-spring-bottom-sheet/releases/36921972
- Warn: release artifact v3.2.0 does not have provenance: https://api.github.com/repos/stipsan/react-spring-bottom-sheet/releases/36739704
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 28 are checked with a SAST tool
Reason
50 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92
- Warn: Project is vulnerable to: GHSA-93q8-gq69-wqmw
- Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg
- Warn: Project is vulnerable to: GHSA-x9w5-v3q2-3rhw
- Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275
- Warn: Project is vulnerable to: GHSA-q8pj-2vqx-8ggc
- Warn: Project is vulnerable to: GHSA-phwq-j96m-2c2q
- Warn: Project is vulnerable to: GHSA-ghr5-ch3p-vcr6
- Warn: Project is vulnerable to: GHSA-434g-2637-qmqr
- Warn: Project is vulnerable to: GHSA-49q7-c7j4-3p7m
- Warn: Project is vulnerable to: GHSA-977x-g7h5-7qgw
- Warn: Project is vulnerable to: GHSA-f7q4-pwc6-w24p
- Warn: Project is vulnerable to: GHSA-fc9h-whq2-v747
- Warn: Project is vulnerable to: GHSA-rc47-6667-2j5j
- Warn: Project is vulnerable to: GHSA-78xj-cgh5-2h22
- Warn: Project is vulnerable to: GHSA-2p57-rm9w-gvfp
- Warn: Project is vulnerable to: GHSA-896r-f27r-55mw
- Warn: Project is vulnerable to: GHSA-9c47-m6qq-7p4h
- Warn: Project is vulnerable to: GHSA-76p3-8jx3-jpfq
- Warn: Project is vulnerable to: GHSA-3rfm-jhwj-7488
- Warn: Project is vulnerable to: GHSA-hhq3-ff78-jv3g
- Warn: Project is vulnerable to: GHSA-5v2h-r2cx-5xgj
- Warn: Project is vulnerable to: GHSA-rrrm-qjm4-v8hf
- Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv
- Warn: Project is vulnerable to: GHSA-f8q6-p94x-37v3
- Warn: Project is vulnerable to: GHSA-xvch-5gv4-984h
- Warn: Project is vulnerable to: GHSA-qrpm-p2h7-hrv2
- Warn: Project is vulnerable to: GHSA-mwcw-c2x4-8c55
- Warn: Project is vulnerable to: GHSA-vxf5-wxwp-m7g9
- Warn: Project is vulnerable to: GHSA-9gr3-7897-pp7m
- Warn: Project is vulnerable to: GHSA-25mp-g6fv-mqxx
- Warn: Project is vulnerable to: GHSA-fmvm-x8mv-47mj
- Warn: Project is vulnerable to: GHSA-c59h-r6p8-q9wc
- Warn: Project is vulnerable to: GHSA-g77x-44xx-532m
- Warn: Project is vulnerable to: GHSA-7gfc-8cq8-jh5f
- Warn: Project is vulnerable to: GHSA-r683-j2x4-v87g
- Warn: Project is vulnerable to: GHSA-hj9c-8jmm-8c52
- Warn: Project is vulnerable to: GHSA-rp65-9cf3-cjxr
- Warn: Project is vulnerable to: GHSA-7fh5-64p2-3v2j
- Warn: Project is vulnerable to: GHSA-hrpp-h998-j3pp
- Warn: Project is vulnerable to: GHSA-p8p7-x288-28g6
- Warn: Project is vulnerable to: GHSA-gcx4-mw62-g8wm
- Warn: Project is vulnerable to: GHSA-x2pg-mjhr-2m5x
- Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw
- Warn: Project is vulnerable to: GHSA-4x5v-gmq8-25ch
- Warn: Project is vulnerable to: GHSA-g4rg-993r-mgx7
- Warn: Project is vulnerable to: GHSA-f5x3-32g6-xq36
- Warn: Project is vulnerable to: GHSA-4wf5-vphf-c2xc
- Warn: Project is vulnerable to: GHSA-72xf-g2v4-qvf3
- Warn: Project is vulnerable to: GHSA-j8xg-fqg3-53r7
Score
3
/10
Last Scanned on 2025-01-27
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn MoreOther packages similar to react-spring-bottom-sheet
react-spring-bottom-sheet-updated
✨ Accessible, 🪄 Delightful, and 🤯 Performant. Built on react-spring for the web, and react-use-gesture.
@denispronin/react-spring-bottom-sheet
✨ Accessible, 🪄 Delightful, and 🤯 Performant. Built on react-spring for the web, and react-use-gesture.
react-spring-bottom-sheet-minimum
✨ Accessible, 🪄 Delightful, and 🤯 Performant. Built on react-spring for the web, and react-use-gesture.
@la55u/react-spring-bottom-sheet-updated
✨ Accessible, 🪄 Delightful, and 🤯 Performant. Built on react-spring for the web, and react-use-gesture.