React Spring Bottom Sheet

https://github.com/wh1teee/react-spring-bottom-sheet-updated
Admin
A highly animated, accessible, and customizable bottom sheet component for React applications, built...
Tokens:4,171
Snippets:26
Trust Score:5.5
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install react-spring-bottom-sheet with npm

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/GET_STARTED.md

Instructions to install the `react-spring-bottom-sheet` library using npm, the Node.js package manager.

```bash
npm i react-spring-bottom-sheet
```

--------------------------------

### Install react-spring-bottom-sheet-updated with yarn

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

This command installs the `react-spring-bottom-sheet-updated` package using yarn, an alternative package manager for JavaScript. It achieves the same result as npm installation.

```bash
yarn add react-spring-bottom-sheet-updated
```

--------------------------------

### Use BottomSheet with TypeScript and snapTo API

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/GET_STARTED.md

Shows how to integrate `BottomSheet` with TypeScript, utilizing `BottomSheetRef` for type safety. It demonstrates programmatic control over the sheet's position using the `snapTo` API, allowing for actions like expanding to full height.

```tsx
import { useRef } from 'react'
import { BottomSheet, BottomSheetRef } from 'react-spring-bottom-sheet'

export default function Example() {
  const sheetRef = useRef<BottomSheetRef>()
  return (
    <BottomSheet open ref={sheetRef}>
      <button
        onClick={() => {
          // Full typing for the arguments available in snapTo, yay!!
          sheetRef.current.snapTo(({ maxHeight }) => maxHeight)
        }}
      >
        Expand to full height
      </button>
    </BottomSheet>
  )
}
```

--------------------------------

### Configure PostCSS for react-spring-bottom-sheet custom CSS

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/GET_STARTED.md

Provides a `postcss.config.js` example demonstrating how to use `postcss-custom-properties-fallback`. This configuration ensures that default CSS variables from `react-spring-bottom-sheet` are available when you copy and customize the library's `style.css` in your project.

```js
module.exports = {
  plugins: {
    // Ensures the default variables are available
    'postcss-custom-properties-fallback': {
      importFrom: require.resolve('react-spring-bottom-sheet/defaults.json'),
    },
  },
}
```

--------------------------------

### Install react-spring-bottom-sheet-updated with npm

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

This command installs the `react-spring-bottom-sheet-updated` package using npm, a popular package manager for JavaScript. It's the standard way to add the library to your project's dependencies.

```bash
npm i react-spring-bottom-sheet-updated
```

--------------------------------

### Implement basic React BottomSheet component

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/GET_STARTED.md

Demonstrates how to import and use the `BottomSheet` component in a React functional component. It shows how to manage the sheet's open state using React's `useState` hook and includes the necessary CSS import.

```jsx
import { useState } from 'react'
import { BottomSheet } from 'react-spring-bottom-sheet'

// if setting up the CSS is tricky, you can add this to your page somewhere:
// <link rel="stylesheet" href="https://unpkg.com/react-spring-bottom-sheet/dist/style.css" crossorigin="anonymous">
import 'react-spring-bottom-sheet/dist/style.css'

export default function Example() {
  const [open, setOpen] = useState(false)
  return (
    <>
      <button onClick={() => setOpen(true)}>Open</button>
      <BottomSheet open={open}>My awesome content here</BottomSheet>
    </>
  )
}
```

--------------------------------

### Example: Delaying Bottom Sheet Open Animation with onSpringStart

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

This example demonstrates how to use the `onSpringStart` event handler with an async function to delay the bottom sheet's opening animation. The sheet waits for data to be fetched before proceeding with the transition, ensuring content is ready when displayed.

```jsx
function Example() {
  const [data, setData] = useState([])
  return (
    <BottomSheet
      onSpringStart={async (event) => {
        if (event.type === 'OPEN') {
          // the bottom sheet gently waits
          const data = await fetch(/* . . . */)
          setData(data)
          // and now we can proceed
        }
      }}
    >
      {data.map(/* . . . */)}
    </BottomSheet>
  )
}
```

--------------------------------

### Customize BottomSheet CSS using custom properties

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/GET_STARTED.md

Lists the CSS custom properties (variables) available for styling the `react-spring-bottom-sheet` component. These variables allow for easy customization of colors, dimensions, and other visual aspects when using the provided CSS.

```css
:root {
  --rsbs-backdrop-bg: rgba(0, 0, 0, 0.6);
  --rsbs-bg: #fff;
  --rsbs-handle-bg: hsla(0, 0%, 0%, 0.14);
  --rsbs-max-w: auto;
  --rsbs-ml: env(safe-area-inset-left);
  --rsbs-mr: env(safe-area-inset-right);
  --rsbs-overlay-rounded: 16px;
}
```

--------------------------------

### API: SNAP Event Type and Usage with onSpringStart

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

Documents the `SNAP` event type, detailing its `source` property ('dragging' or 'custom'). The example demonstrates how to use the `onSpringStart` prop to detect when a spring animation begins due to a user drag gesture ending in a snap.

```APIDOC
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.
```

```jsx
function Example() {
  return (
    <BottomSheet
      onSpringStart={(event) => {
        if (event.type === 'SNAP' && event.source === 'dragging') {
          console.log('Starting a spring animation to user selected snap point')
        }
      }}
    />
  )
}
```

--------------------------------

### Utilize BottomSheetRef for TypeScript Integration

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

This example illustrates how to integrate `BottomSheet` with TypeScript, specifically using `BottomSheetRef` for type-safe access to the sheet's methods like `snapTo`. It demonstrates how to expand the sheet to its full height programmatically.

```tsx
import { useRef } from 'react'
import { BottomSheet, BottomSheetRef } from 'react-spring-bottom-sheet'

export default function Example() {
  const sheetRef = useRef<BottomSheetRef>()
  return (
    <BottomSheet open ref={sheetRef}>
      <button
        onClick={() => {
          // Full typing for the arguments available in snapTo, yay!!
          sheetRef.current.snapTo(({ maxHeight }) => maxHeight)
        }}
      >
        Expand to full height
      </button>
    </BottomSheet>
  )
}
```

--------------------------------

### React BottomSheet: Handle Custom SnapTo Source with onSpringEnd

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

This example shows how to use `ref.snapTo` to programmatically move the bottom sheet to a specific snap point while providing a custom `source` string. It also demonstrates how to use `onSpringEnd` to detect when this imperative transition has completed, allowing for post-transition logic.

```jsx
function Example() {
  const sheetRef = useRef()
  return (
    <BottomSheet
      ref={sheetRef}
      snapPoints={({ minHeight, maxHeight }) => [minHeight, maxHeight]}
      onSpringEnd={(event) => {
        if (event.type === 'SNAP' && event.source === 'snap-to-bottom') {
          console.log(
            'Just finished an imperativ transition to the bottom snap point'
          )
        }
      }}
    >
      <button
        onClick={() => sheetRef.current.snapTo(0, { source: 'snap-to-bottom' })}
      >
        Snap to bottom
      </button>
    </BottomSheet>
  )
}
```

--------------------------------

### React Spring Bottom Sheet API Props

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

This section details the various props available for customizing the `BottomSheet` component, including their types, purposes, and usage examples. Props are spread onto the underlying `<animated.div>` instance, and the component is mounted in a `@radix-ui/react-portal`.

```APIDOC
API
props:
  All props (e.g., className, style) are spread onto the underlying <animated.div> instance, selectable via `[data-rsbs-root]`. Mounted in a @radix-ui/react-portal at the bottom of <body>.

  open:
    Type: boolean
    Description: The only required prop beyond `children`. It's a controlled prop; setting it to `false` is necessary to close the sheet. When `false`, only a @reach/dialog placeholder renders, ensuring components unmount. This prevents interaction with a closed sheet and optimizes accessibility.

  onDismiss:
    Type: () => void
    Description: Callback invoked when the user signals dismissal: hitting `esc` key, tapping backdrop, or swiping sheet to bottom.

  snapPoints:
    Type: (state) => number | number[]
    Description: A pure function that returns a single number or an array of numbers to customize sheet snap positions.
    State properties:
      headerHeight: current measured height of the header.
      footerHeight: height of the footer if provided.
      height: current height of the sheet.
      minHeight: minimum height needed to avoid a scrollbar (same as maxHeight if not enough height available).
      maxHeight: maximum available page height (window.innerHeight, 100vh).

  defaultSnap:
    Type: number | (state) => number
    Description: Provides the default opening position of the sheet. Can be a number or a callback returning a number.
    State properties: Same as `snapPoints` plus `snapPoints` (array of all snap points) and `lastSnap` (previously selected snap point).

  header:
    Type: ReactNode
    Description: Supports the same value type as the `children` prop.

  footer:
    Type: ReactNode
    Description: Supports the same value type as the `children` prop.

  sibling:
    Type: ReactNode
    Description: Supports the same value type as the `sibling` prop. Renders as a child of `[data-rsbs-root]`, sibling to `[data-rsbs-backdrop]` and `[data-rsbs-overlay]`. Allows access to animation state and rendering elements on top of the sheet, while being outside the overlay itself.

  initialFocusRef:
    Type: React.Ref | false
    Description: A React ref to the element that should receive keyboard focus when opening. If not provided, the first interactive element is automatically selected. If set to false, keyboard focus when opening is disabled.

  blocking:
    Type: boolean
    Description: 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.
```

```jsx
<BottomSheet
  // Allow the user to select between minimun height to avoid a scrollbar, and fullscren
  snapPoints={({ minHeight, maxHeight }) => [minHeight, maxHeight]}
/>
```

```jsx
<BottomSheet
  // the first snap points height depends on the content, while the second one is equivalent to 60vh
  snapPoints={({ minHeight, maxHeight }) => [minHeight, maxHeight / 0.6]}
  // Opens the largest snap point by default, unless the user selected one previously
  defaultSnap={({ lastSnap, snapPoints }) =>
    lastSnap ?? Math.max(...snapPoints)
  }
/>
```

--------------------------------

### React BottomSheet: Attaching a Ref to the Component

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

This example demonstrates how to attach a React `ref` to the `BottomSheet` component. Setting a ref allows direct access to the sheet's imperative methods and properties, enabling programmatic control over its behavior.

```jsx
export default function Example() {
  const sheetRef = React.useRef()
  return <BottomSheet open ref={sheetRef} />
}
```

--------------------------------

### API: height Ref Property and Usage

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

Documents the `height` property available via the sheet's ref, which provides the current height (snap point) of the bottom sheet. This value updates outside the React render cycle for performance. The example shows how to log the height before, during, and after a transition.

```APIDOC
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.
```

```jsx
export default function Example() {
  const sheetRef = React.useRef()
  return (
    <BottomSheet
      ref={sheetRef}
      onSpringStart={() => {
        console.log('Transition from:', sheetRef.current.height)
        requestAnimationFrame(() =>
          console.log('Transition to:', sheetRef.current.height)
        )
      }}
      onSpringEnd={() =>
        console.log('Finished transition to:', sheetRef.current.height)
      }
    />
  )
}
```

--------------------------------

### API Reference: onSpringStart Event Handler

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

The `onSpringStart` event handler is fired on 'OPEN', 'RESIZE', 'SNAP', or 'CLOSE' events. It can be an async function or return a Promise, allowing the bottom sheet to delay its open animation until asynchronous work, such as data loading, is complete.

```APIDOC
onSpringStart:
  Type: (event: SpringEvent) => void
  Fired on: OPEN | RESIZE | SNAP | CLOSE
  Behavior: Can return a Promise or be async to delay open animation.
```

--------------------------------

### Implement Basic BottomSheet in React

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

This snippet demonstrates the fundamental usage of `BottomSheet` in a React component. It shows how to import the component, manage its open state using `useState`, and include the necessary CSS stylesheet for styling. The sheet opens when a button is clicked.

```jsx
import { useState } from 'react'
import { BottomSheet } from 'react-spring-bottom-sheet'

// if setting up the CSS is tricky, you can add this to your page somewhere:
// <link rel="stylesheet" href="https://unpkg.com/react-spring-bottom-sheet/dist/style.css" crossorigin="anonymous">
import 'react-spring-bottom-sheet/dist/style.css'

export default function Example() {
  const [open, setOpen] = useState(false)
  return (
    <>
      <button onClick={() => setOpen(true)}>Open</button>
      <BottomSheet open={open}>My awesome content here</BottomSheet>
    </>
  )
}
```

--------------------------------

### API: snapTo Ref Method for BottomSheet

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

Documents the `snapTo` method available via the sheet's ref, which animates the sheet to a new snap point. It can accept a number (height in px) or a callback function to dynamically determine the snap point. Optional `source` and `velocity` parameters can be provided.

```APIDOC
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).
```

```js
ref.current.snapTo(({ // Showing all the available props
  headerHeight, footerHeight, height, minHeight, maxHeight, snapPoints, lastSnap }) =>
  // Selecting the largest snap point, if you give it a number that doesn't match a snap point then it'll
  // select whichever snap point is nearest the value you gave
  Math.max(...snapPoints)
)
```

```js
ref.current.snapTo(({ snapPoints }) => Math.min(...snapPoints), {
  // Each property is optional, here showing their default values
  source: 'custom',
  velocity: 1,
})
```

--------------------------------

### API: onSpringEnd Event Handler

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

Documents the `onSpringEnd` prop, a callback function fired when a spring animation completes, including for the `CLOSE` event. It supports `async/await` and Promises for delaying unmounting, useful for cleanup logic.

```APIDOC
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.
```

--------------------------------

### API Reference: SpringEvent Structure

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

All bottom sheet events receive a `SpringEvent` object as an argument. This object always includes a `type` property, which can be 'OPEN', 'RESIZE', 'SNAP', or 'CLOSE', indicating the specific event scenario.

```APIDOC
SpringEvent:
  type: 'OPEN' | 'RESIZE' | 'SNAP' | 'CLOSE'
  payload: Varies depending on event type
```

--------------------------------

### Configure PostCSS for BottomSheet Custom Properties Fallback

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

This configuration snippet for `postcss.config.js` shows how to ensure default CSS custom properties for `react-spring-bottom-sheet` are available. It uses `postcss-custom-properties-fallback` to import default values, facilitating consistent styling.

```javascript
module.exports = {
  plugins: {
    // Ensures the default variables are available
    'postcss-custom-properties-fallback': {
      importFrom: require.resolve('react-spring-bottom-sheet/defaults.json'),
    },
  },
}
```

--------------------------------

### API: skipInitialTransition Prop

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

Documents the `skipInitialTransition` boolean prop. Setting it to `true` prevents the default spring animation for the initial open state, causing the sheet to render immediately in its default position, which can avoid distracting opening transitions.

```APIDOC
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.
```

--------------------------------

### API Reference: expandOnContentDrag Prop

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

The `expandOnContentDrag` boolean prop, disabled by default, allows the bottom sheet to be expanded by dragging its content area. By default, expansion is limited to dragging the header or overlay.

```APIDOC
expandOnContentDrag:
  Type: boolean
  Description: Enables expanding the bottom sheet by dragging its content. Disabled by default.
```

--------------------------------

### API Reference: RESIZE SpringEvent Type

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

The `RESIZE` event type within `SpringEvent` is triggered when the window resizes or when the header, footer, or content height changes, affecting valid snap points. The `source` property indicates the cause of the resize, which can be 'window', 'maxheightprop', or 'element'.

```APIDOC
RESIZE (SpringEvent type):
  Type: { source: 'window' | 'maxheightprop' | 'element' }
  Fires whenever: Window resize, or header/footer/content height changes affecting snap points.
  source:
    - 'window': Caused by window.onresize event.
    - 'maxheightprop': Caused by maxHeight prop change.
    - 'element': Caused by header/footer/content resize observers.
```

--------------------------------

### Customize BottomSheet Appearance with CSS Custom Properties

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

This snippet lists the CSS custom properties available for styling `react-spring-bottom-sheet`. These variables allow developers to control aspects like backdrop background, sheet background, handle color, maximum width, and border-radius directly from CSS.

```css
:root {
  --rsbs-backdrop-bg: rgba(0, 0, 0, 0.6);
  --rsbs-bg: #fff;
  --rsbs-handle-bg: hsla(0, 0%, 0%, 0.14);
  --rsbs-max-w: auto;
  --rsbs-ml: env(safe-area-inset-left);
  --rsbs-mr: env(safe-area-inset-right);
  --rsbs-overlay-rounded: 16px;
}
```

--------------------------------

### API Reference: onSpringCancel Event Handler

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

The `onSpringCancel` event handler is fired when an 'OPEN' or 'CLOSE' animation is interrupted. This can occur if the user dismisses the sheet, presses 'esc', the parent component sets `open` to `false` prematurely, or a 'RESIZE' event happens. It also fires if the sheet is unmounted before completing its animation, ensuring cleanup of `body-scroll-lock` and `focus-trap`.

```APIDOC
onSpringCancel:
  Type: (event: SpringEvent) => void
  Fired on: OPEN | CLOSE
  Triggers:
    - OPEN: User swipes below fold, hits esc, parent sets open=false, RESIZE event.
    - CLOSE: User reopens before animation completes, component unmounts prematurely.
```

--------------------------------

### API Reference: scrollLocking Prop

Source: https://github.com/wh1teee/react-spring-bottom-sheet-updated/blob/main/README.md

The `scrollLocking` boolean prop controls whether the bottom sheet prevents scrolling on `document.body` to handle touch interactions. It is enabled by default but can be aggressive, affecting elements like `<input type="range" />`. Elements can be excluded from scroll locking by adding the `[data-body-scroll-lock-ignore]` attribute.

```APIDOC
scrollLocking:
  Type: boolean
  Description: Controls body scroll locking for touch interactions. Enabled by default. Use [data-body-scroll-lock-ignore] to exclude elements.
```
Tokens:
Raw