📦 Installation

1npm install react-modal-sheet

Peer dependencies

The gestures and animations are handled by the excellent Motion library so before you can start using this library you need to install motion:

1npm install motion

[!IMPORTANT] If you are still using the old framer-motion package you need to upgrade to motion as react-modal-sheet is now built on top of the new motion package. Version v3.5.0 and older are compatible with framer-motion.

---

📚 Table of contents

• Usage
• Props
• Methods and properties
• Compound Components
• Advanced usage
• Customization
• Accessibility
• Troubleshooting

---

💻 Usage

1import { Sheet } from 'react-modal-sheet';
2import { useState } from 'react';
3
4function Example() {
5  const [isOpen, setOpen] = useState(false);
6
7  return (
8    <>
9      <button onClick={() => setOpen(true)}>Open sheet</button>
10
11      <Sheet isOpen={isOpen} onClose={() => setOpen(false)}>
12        <Sheet.Container>
13          <Sheet.Header />
14          <Sheet.Content>{/* Your sheet content goes here */}</Sheet.Content>
15        </Sheet.Container>
16        <Sheet.Backdrop />
17      </Sheet>
18    </>
19  );
20}

The Sheet component follows the Compound Component pattern in order to provide a flexible yet powerful API for creating highly customizable bottom sheet components.

Since the final bottom sheet is composed from smaller building blocks (Container, Content, Scroller, Header, and Backdrop) you are in total control over the rendering output. So for example, if you don't want to have any backdrop in your sheet then you can just skip rendering it instead of passing some prop like renderBackdrop={false} to the main sheet component. Cool huh? 😎

Also, by constructing the sheet from smaller pieces makes it easier to apply any necessary accessibility related properties to the right components without requiring the main sheet component to be aware of them. You can read more about accessibility in the Accessibility section.

🎛️ Props

Name	Required	Default	Description
children	yes		Use Sheet.Container/Content/Header/Backdrop to compose your bottom sheet.
isOpen	yes		Boolean that indicates whether the sheet is open or not.
onClose	yes		Callback fn that is called when the sheet is closed by the user.
disableDrag	no	false	Disable drag for the whole sheet.
disableScrollLocking	no	false	Disable scroll locking for the body element while sheet is open. Can be useful if you face issues with input elements and the iOS virtual keyboard. See related issue.
detent	no	'full-height'	The detent in which the sheet should be in when opened. Available values: 'full-height' or 'content-height'.
onOpenStart	no		Callback fn that is called when the sheet opening animation starts.
onOpenEnd	no		Callback fn that is called when the sheet opening animation is completed.
onCloseStart	no		Callback fn that is called when the sheet closing animation starts.
onCloseEnd	no		Callback fn that is called when the sheet closing animation is completed.
onSnap	no		Callback fn that is called with the current snap point index when the sheet snaps to a new snap point. Requires snapPoints prop.
snapPoints	no		Eg. [-50, 0.5, 100, 0] - where positive values are pixels from the bottom of the sheet and negative from the top. Values between 0-1 represent percentages, eg. 0.5 means 50% of sheet height. Prefer using 1 for representing a snap point for a fully visible sheet.
initialSnap	no	0	Initial snap point when sheet is opened (index from snapPoints).
modalEffectRootId	no		The id of the element where the main app is mounted, eg. "root". Enables iOS modal effect.
modalEffectThreshold	no	0	Threshold value between 0-1 which determines when the iOS modal effect will start while dragging the sheet - 0 corresponding to the start of the drag (0% has been dragged into view) and 1 corresponding to the end of the drag (100% of the sheet is visible).
tweenConfig	no	{ ease: 'easeOut', duration: 0.2 }	Overrides the config for the sheet tween transition when the sheet is opened, closed, or snapped to a point.
mountPoint	no	document.body	HTML element that should be used as the mount point for the sheet.
prefersReducedMotion	no	false	Skip sheet animations (sheet instantly snaps to desired location).
dragVelocityThreshold	no	500	How fast the sheet must be flicked down to close. Higher values make the sheet harder to close.
dragCloseThreshold	no	0.6	The portion of the sheet which must be dragged off-screen before it will close.

⚙️ Methods and properties

snapTo(index)

Imperative method that can be accessed via a ref for snapping to a snap point in given index.

1import { Sheet, SheetRef } from 'react-modal-sheet';
2import { useState, useRef } from 'react';
3
4const snapPoints = [1, 0.5, 0];
5
6function Example() {
7  const [isOpen, setOpen] = useState(false);
8  const ref = useRef<SheetRef>(null);
9  const snapTo = (i: number) => ref.current?.snapTo(i);
10
11  return (
12    <>
13      <button onClick={() => setOpen(true)}>Open sheet</button>
14
15      {/* Opens to 50% since initial index is 1 */}
16      <Sheet
17        ref={ref}
18        isOpen={isOpen}
19        onClose={() => setOpen(false)}
20        initialSnap={1}
21        snapPoints={snapPoints}
22        onSnap={(snapIndex) =>
23          console.log('> Current snap point index:', snapIndex)
24        }
25      >
26        <Sheet.Container>
27          <Sheet.Content>
28            <button onClick={() => snapTo(0)}>Snap to index 0</button>
29            <button onClick={() => snapTo(1)}>Snap to index 1</button>
30            <button onClick={() => snapTo(2)}>Snap to index 2</button>
31            <button onClick={() => snapTo(3)}>Snap to index 3</button>
32          </Sheet.Content>
33        </Sheet.Container>
34      </Sheet>
35    </>
36  );
37}

Motion value y

The y value is an internal MotionValue that represents the distance to the top most position of the sheet when it is fully open. So for example the y value is zero when the sheet is completely open.

Similarly to the snapTo method the y value can be accessed via a ref.

The y value can be useful for certain situtations, eg. when you want to combine snap points with scrollable sheet content and ensure that the content stays properly scrollable at any snap point.

Below you can see a simplified example of this situation:

1import { Sheet, SheetRef } from 'react-modal-sheet';
2import { useState, useRef } from 'react';
3
4const snapPoints = [1, 0.5, 0];
5
6function Example() {
7  const [isOpen, setOpen] = useState(false);
8  const ref = useRef<SheetRef>(null);
9
10  return (
11    <>
12      <button onClick={() => setOpen(true)}>Open sheet</button>
13
14      <Sheet
15        isOpen={isOpen}
16        onClose={() => setOpen(false)}
17        initialSnap={1}
18        snapPoints={snapPoints}
19      >
20        <Sheet.Container>
21          {/**
22           * Since `Sheet.Content` is a `motion.div` it can receive motion values
23           * in it's style prop which allows us to utilise the exposed `y` value.
24           *
25           * By syncing the padding bottom with the `y` motion value we introduce
26           * an offset that ensures that the sheet content can be scrolled all the
27           * way to the bottom in every snap point.
28           */}
29          <Sheet.Content style={{ paddingBottom: ref.current?.y }}>
30            <Sheet.Scroller draggableAt="both">
31              {/* Some content here that makes the sheet content scrollable */}
32            </Sheet.Scroller>
33          </Sheet.Content>
34        </Sheet.Container>
35      </Sheet>
36    </>
37  );
38}

[!NOTE] As this use case is quite a common one, the Sheet.Scroller component has a built-in prop called autoPadding which automatically keeps the bottom padding in sync with the animated y value.

See Automatic padding with snap points for more details.

Detents

By default the sheet will take the full height of the page minus top padding and safe area inset. If you want the sheet height to be based on it's content you can pass detent="content-height" prop to the Sheet component:

1function Example() {
2  const [isOpen, setOpen] = useState(false);
3
4  return (
5    <Sheet
6      isOpen={isOpen}
7      onClose={() => setOpen(false)}
8      detent="content-height"
9    >
10      <Sheet.Container>
11        <Sheet.Content>
12          <Sheet.Scroller>
13            <div style={{ height: 200 }}>Some content</div>
14          </Sheet.Scroller>
15        </Sheet.Content>
16      </Sheet.Container>
17    </Sheet>
18  );
19}

If the sheet height changes dynamically the sheet will grow until it hits the maximum full height after which it becomes scrollable.

It is possible to use snap points with detent="content-height" but the snap points are restricted by the content height. For example if one of the snap points is 800px and the sheet height is only 700px then snapping to the 800px snap point would only snap to 700px since otherwise the sheet would become detached from the bottom.

ℹ️ If you are wondering where the term detent comes from it's from Apple's Human Interface Guidelines.

🧩 Compound Components

Sheet

Sheet is the root element that wraps the whole sheet. It renders a fixed positioned wrapper element that covers the whole screen to contain the actual sheet that is animated in (don't worry the root element is not interactive when the sheet is closed). All sheet compound components should be rendered within Sheet.

🖥 Rendered element: motion.div.

Sheet.Container

Sheet container is positioned above the sheet backdrop and by default adds a small shadow and rounded corners to the sheet. Sheet.Content and Sheet.Header should be rendered inside Sheet.Container.

🖥 Rendered element: motion.div.

Sheet.Header

Sheet header acts as a drag target and has a dragging direction indicator. Rendering any children inside Sheet.Header replaces the default header.

🖥 Rendered element: motion.div.

Header props

Name	Required	Default	Description
disableDrag	no	false	Disable drag for the sheet header.

Sheet.Content

Sheet content acts as a drag target and can be used in conjunction with Sheet.Scroller to make sure that content which doesn't fit inside the sheet becomes scrollable.

🖥 Rendered element: motion.div.

Content props

Name	Required	Default	Description
disableDrag	no	false	Disable drag for the sheet content.

Sheet.Scroller

Sheet scroller can be used to make the whole sheet content or parts of it scrollable in a way that drag gestures are properly disabled and enabled based on the scroll state. See the Scrolling on touch devices section for more details.

🖥 Rendered element: motion.div.

Scroller props

Name	Required	Default	Description
draggableAt	no	"top"	Should the drag be enabled when the element is scrolled either to the top, bottom, or both. Available values: top, bottom, both.
disableScroll	no	false	Disable scrolling. This can be combined with snap points to make the sheet scroller only scrollable at a given snap point (usually the top position).
autoPadding	no	false	Automatically apply padding bottom to the scroller based on the dragged distance to ensure that content can be scrolled to the bottom at any snap point.

Sheet.Backdrop

Sheet backdrop is a translucent overlay that helps to separate the sheet from it's background. By default the backdrop doesn't have any interaction attached to it but if you, for example, want to close the sheet when the backdrop is clicked you can provide tap handler to it which will change the rendered element from div to button.

⚠️ Note: as the element is a motion component you need to use onTap instead of onClick if you want to add a click handler to it.

🖥 Rendered element: motion.div or motion.button.

✨ Advanced usage

⌨️ Virtual keyboard avoidance

A common problem with React Modal Sheet is that since the sheet is rendered as a fixed positioned element it doesn't move when the virtual keyboard is opened which can lead to the keyboard covering the input elements.

Handling the virtual keyboard on mobile devices can be quite tricky. It doesn't help that the Web doesn't yet have widely supported APIs for working with the virtual keyboard.

⚠️ Note: This library does not provide any official built-in solution for keyboard avoidance!

This is because it is not possible for the library to know how your sheet content is structured and how the sheet should behave when the keyboard is opened.

However, there are some strategies that you can use to handle the virtual keyboard:

1. Design your sheet content in a way that the input elements are positioned at the top of the sheet so that they are not covered by the keyboard. This is the easiest solution and if you look at popular mobile apps you can see that they often have input elements at the top of the screen exactly for this reason.

2. Listen to changes in the visualViewport, see Visual Viewport API, and change styles like padding on the sheet content to move the input up when the keyboard is opened. See the AvoidKeyboard component code and demo in the example app for a simple example of this. The example is based on a custom useAnimatedVirtualKeyboard hook which you can copy to your project at your own risk. Note that at least on iOS there is a noticeable delay when the keyboard is opened and when the resize event is fired for the visualViewport.

3. Use the experimental VirtualKeyboard API to detect when the virtual keyboard is opened and adjust the sheet content accordingly. Note that this API is not yet widely supported in browsers, but it will most likely produce the best result.

📱 Scrolling on touch devices

Scrolling and dragging are the same gesture on touch devices which can create problems when you want to have scrollable content inside the sheet. React Modal Sheet provides a Sheet.Scroller component that is able to automatically disable and enable dragging inside the Sheet.Content component based on the scroll state. There are three modes for the Sheet.Scroller reflected in the draggableAt prop:

1. Enable dragging when the scroller is not yet scrolled - it is at the top position.
2. Enable dragging when the scroller is scrolled all the way to the bottom - it is at the bottom position.
3. Enable dragging in both positions.

The scroller component is in-between these states when the user has scrolled only some amount. Dragging is always disabled in this in-between state in order to avoid it getting mixed with dragging gestures. The Sheet.Scroller component applies the special handling only for touch devices.

The default value for the draggableAt prop is top which should be a good default for most use cases. You shouldn't need bottom or both unless you have scrollable content inside a sheet that also has snap points.

1function ScrollableExample() {
2  return (
3    <Sheet>
4      <Sheet.Container>
5        <Sheet.Header />
6        <Sheet.Content>
7          <Sheet.Scroller>{/*...*/}</Sheet.Scroller>
8        </Sheet.Content>
9      </Sheet.Container>
10      <Sheet.Backdrop />
11    </Sheet>
12  );
13}

Disabling scroll manually

You can also disable scrolling manually by passing disableScroll prop to the Sheet.Scroller component. This can be useful if you want to have a scrollable sheet but only at a certain snap point.

For example, if you have a snap point at the top of the sheet and you want to make the content scrollable only when the sheet is at that snap point, you can do the following:

1const snapPoints = [1, 0.5, 0];
2const initialSnap = 1;
3
4function DisableScrollExample() {
5  const [currentSnap, setCurrentSnap] = useState(initialSnap);
6
7  return (
8    <Sheet
9      initialSnap={initialSnap}
10      snapPoints={snapPoints}
11      onSnap={setCurrentSnap}
12    >
13      <Sheet.Container>
14        <Sheet.Header />
15        <Sheet.Content>
16          <Sheet.Scroller draggableAt="top" disableScroll={currentSnap !== 0}>
17            {/*...*/}
18          </Sheet.Scroller>
19        </Sheet.Content>
20      </Sheet.Container>
21      <Sheet.Backdrop />
22    </Sheet>
23  );
24}

Automatic padding with snap points

If you are using snap points and want to make sure that the content is scrollable at all snap points you can use the autoPadding prop on the Sheet.Scroller component.

This will automatically apply padding to the bottom of the scroller based on the dragged distance to ensure that content can be scrolled to the bottom at any snap point.

1import { Sheet } from 'react-modal-sheet';
2import { useState } from 'react';
3
4const snapPoints = [-50, 0.5, 0];
5const initialSnap = 1;
6
7function AutoPaddingExample() {
8  return (
9    <Sheet initialSnap={initialSnap} snapPoints={snapPoints}>
10      <Sheet.Container>
11        <Sheet.Header />
12        <Sheet.Content>
13          <Sheet.Scroller autoPadding draggableAt="both">
14            {/*...*/}
15          </Sheet.Scroller>
16        </Sheet.Content>
17      </Sheet.Container>
18      <Sheet.Backdrop />
19    </Sheet>
20  );
21}

[!NOTE] For backwards compatibility the autoPadding prop is disabled by default but it will be enabled by default in the next major version.

🪟 iOS Modal View effect

In addition to the Sheet.Backdrop it's possible to apply a scaling effect to the main app element to highlight the modality of the bottom sheet. This effect mimics the iOS Modal View presentation style to bring more focus to the sheet and add some delight to the user experience.

To enable this effect you can provide the id of the root element where your application is mounted:

1function Example() {
2  return <Sheet modalEffectRootId="root">{/*...*/}</Sheet>;
3}

[!IMPORTANT] ⚠️ Limitations: Since the effect is applied to the root element it will NOT work as desired if the HTML body element is scrolled down at all. One way to avoid this is to use something like height: 100vh; and overflow: auto; on the root element to make it fill the whole screen and be scrollable instead of the body element. You can check the example apps root styles for a working example of this.

Controlling the effect

You can control the start threshold of the effect with the modalEffectThreshold prop which should have a value between 0 and 1 representing the fraction at which the effect starts relative to the dragging distance. So for example, a value of 0.5 means the effect will start when the sheet is dragged halfway and 0.7 would mean the effect will start when the sheet is dragged 70% of the way to the top. The default value is 0 which means that the effect will start as soon as the sheet is opened or dragged into view.

[!NOTE] If you are using snapPoints the start threshold is calculated based on the second snap point so that when the sheet is snapping to the first snap point, meaning the sheet is fully open, the effect will only apply for that snap point range and not for the whole draggable distance.

This gives a more natural UX and follows the native iOS effect more closely.

You can still override this behavior by providing a custom modalEffectThreshold value.

🎨 Customization

The default styles for the Sheet component somewhat follows the styles of the previously mentioned iOS Modal View. However, if these default styles are not to your liking it's easy to make changes to them: you can provide a custom header or you can overwrite any style with CSS via the exposed class names.

Custom header

Adding a custom header is as simple as providing your own header as the child component to Sheet.Header:

1function Example() {
2  return (
3    <Sheet>
4      <Sheet.Container>
5        <Sheet.Header>
6          <YourCustomSheetHeader />
7        </Sheet.Header>
8        <Sheet.Content>{/*...*/}</Sheet.Content>
9      </Sheet.Container>
10      <Sheet.Backdrop />
11    </Sheet>
12  );
13}

Custom styles

You can add your own styles or override the default sheet styles via the exposed class names. Note that you might need to use !important for style overrides since the inner styles are applied as inline styles which have higher specificity.

Vanilla CSS

1.react-modal-sheet-backdrop {
2  /* custom styles */
3}
4.react-modal-sheet-container {
5  /* custom styles */
6}
7.react-modal-sheet-header {
8  /* custom styles */
9}
10.react-modal-sheet-drag-indicator {
11  /* custom styles */
12}
13.react-modal-sheet-content {
14  /* custom styles */
15}

CSS-in-JS

1import { Sheet } from 'react-modal-sheet';
2import { styled } from 'styled-components';
3import { useState } from 'react';
4
5const CustomSheet = styled(Sheet)`
6  .react-modal-sheet-backdrop {
7    /* custom styles */
8  }
9  .react-modal-sheet-container {
10    /* custom styles */
11  }
12  .react-modal-sheet-header {
13    /* custom styles */
14  }
15  .react-modal-sheet-drag-indicator {
16    /* custom styles */
17  }
18  .react-modal-sheet-content {
19    /* custom styles */
20  }
21`;
22
23function Example() {
24  const [isOpen, setOpen] = useState(false);
25
26  return (
27    <>
28      <button onClick={() => setOpen(true)}>Open sheet</button>
29
30      <CustomSheet isOpen={isOpen} onClose={() => setOpen(false)}>
31        <Sheet.Container>
32          <Sheet.Header />
33          <Sheet.Content>{/*...*/}</Sheet.Content>
34        </Sheet.Container>
35        <Sheet.Backdrop />
36      </CustomSheet>
37    </>
38  );
39}

♿️ Accessibility

By default, react-modal-sheet doesn't include any built-in accessibility properties in order to not make any assumptions and to support a wide range of use cases. Additionally, not including 3rd party libraries for features like focus trapping or screen reader support makes it possible to utilize any accessibility libraries that your project may already use, eg. React Aria. This also helps to reduce JS bloat by not including similar libraries multiple times in your app bundle.

The example below utilizes React Aria to achieve an accessible modal-like bottom sheet that can be closed via a button rendered inside a custom sheet header.

ℹ️ The example was built by following the React Aria's useDialog documentation.

1import { Sheet } from 'react-modal-sheet';
2import { useRef } from 'react';
3import { useOverlayTriggerState } from 'react-stately';
4
5import {
6  useOverlay,
7  useModal,
8  OverlayProvider,
9  FocusScope,
10  useButton,
11  useDialog,
12} from 'react-aria';
13
14function A11yExample() {
15  const sheetState = useOverlayTriggerState({});
16  const openButtonRef = useRef(null);
17  const openButton = useButton({ onPress: sheetState.open }, openButtonRef);
18
19  return (
20    <div>
21      <button {...openButton.buttonProps} ref={openButtonRef}>
22        Open sheet
23      </button>
24
25      <Sheet isOpen={sheetState.isOpen} onClose={sheetState.close}>
26        <OverlayProvider>
27          <FocusScope contain autoFocus restoreFocus>
28            <SheetComp sheetState={sheetState} />
29          </FocusScope>
30        </OverlayProvider>
31      </Sheet>
32    </div>
33  );
34}
35
36function SheetComp({ sheetState }) {
37  const containerRef = useRef(null);
38  const dialog = useDialog({}, containerRef);
39  const overlay = useOverlay(
40    { onClose: sheetState.close, isOpen: true, isDismissable: true },
41    containerRef
42  );
43
44  const closeButtonRef = useRef(null);
45  const closeButton = useButton(
46    { onPress: sheetState.close, 'aria-label': 'Close sheet' },
47    closeButtonRef
48  );
49
50  useModal();
51
52  // In real world usage this would be a separate React component
53  const customHeader = (
54    <div>
55      <span {...dialog.titleProps}>Some title for sheet</span>
56      <button {...closeButton.buttonProps}>🅧</button>
57    </div>
58  );
59
60  return (
61    <>
62      <Sheet.Container
63        {...overlay.overlayProps}
64        {...dialog.dialogProps}
65        ref={containerRef}
66      >
67        <Sheet.Header>{customHeader}</Sheet.Header>
68        <Sheet.Content>{/*...*/}</Sheet.Content>
69      </Sheet.Container>
70      <Sheet.Backdrop />
71    </>
72  );
73}

If you want to see a more real-world-like implementation you can take a look at the Slack example and try out the related demo (optimized for mobile).

🔩 Building a reusable sheet

In your projects it might make sense to build a reusable bottom sheet that has all the accessibility features included and can then be easily used in various places in the project. Take a look at the A11ySheet example to get some insight on how to build such a component. By incorporating all the accessibility features inside your own reusable component you don't need to repeat them every time you want to use a bottom sheet in your app.

🐛 Troubleshooting

The sheet doesn't open when using StrictMode

If you are using React StrictMode the sheet animations might not work as expected. This seems to be an issue in the motion library and I haven't been able to find a good solution for it yet. You see all motion issues related to the StrictMode here. Easiest solution is to just not to use StrictMode 🤷‍♂️