react-material-overlay

Performant, easy to use, customizable and extendable library provides a generic and flexible way to implement and use overlays (like modals, dialogs, lightboxes, and bottom sheets) in your React applications using Material UI ^V6. It supports stacking overlays and integrates seamlessly with the browser's history, enabling users to navigate overlays using the browser’s back button.

Overview

- Ease of Use: Simple API for pushing and popping overlays without needing to manage component state manually.
- Generic Overlays: Easily manage different types of overlays (Modal, Alert Dialog, Lightbox, and Bottom Sheet) with customizable options.
- Multiple Overlay Management: Manage multiple overlays at the same time with an easy-to-use stack mechanism.
- Multiple containers support: Different containers can be set up with unique options for various overlay types.
- Overlay Stacking: Overlays are managed on a stack, ensuring the correct order of opening and closing.
- Browser History Integration: Works seamlessly with browser history, allowing users to navigate back through overlays using the browser's back button.
- Modular API: Provides individual APIs for pushing different types of overlays: modals, lightboxes, bottom sheets, and alert dialogs.
- Custom Overlay Support: you can add custom overlays and manage them using the RmoStack API.
- Dynamic Options: Specify different options for each overlay instance to customize behavior and appearance.
- Theming Support: Fully compatible with MUI's theming system, allowing for consistent styling across your application.
- TypeScript: type definitions come built-in in the package
- Accessibility Support: Built with accessibility in mind, adhering to MUI's best practices.
- Fully responsive UI
- Customizable and Extendable
- RTL Support

Installation

``bash

npm install react-material-overlay

`

$3

`bash

npm install @mui/material @emotion/react @emotion/styled

`

Table of Contents

- Usage
- Basic Example
- Modal Overlay
- Alert Dialog Overlay
- Lightbox Overlay
- Bottom Sheet Overlay
- Closing Overlays
- Custom Overlays
- Caveats
- API Reference
- Modal
- Alert Dialog
- Lightbox
- Bottom Sheet
- Close APIs
- RmoStack

Usage

Using react-material-overlay is straightforward. To get started, simply add the desired overlay container component (e.g., ModalContainer, AlertDialogContainer, LightboxContainer, or BottomSheetContainer) to your React component tree. Then, utilize the corresponding push API method, such as pushModal, to display the overlay.

To enable support for multiple containers, you must specify a containerId for the desired container and use it in each push API, to do this, add the containerId to the push options object.

$3

In this example, we'll use the ModalContainer and the pushModal method to open our modal when a button is clicked.

The ModalContainer component handles rendering and stacking of the modals you push.

`jsx
import React from 'react';
import { Button, ThemeProvider } from '@mui/material';
import { ModalContainer, pushModal } from 'react-material-overlay';

const SomeComponent = React.lazy(() => import('./SomeComponent'));

function App() {
return (
your application theme/}>
onClick={() => {
// push new modal to default modal container
pushModal();
}}
>
open modal


onClick={() => {
// push new overlay to fullscreen modal container
pushModal(, {containerId: 'fullscreen'});
}}
>
open modal


{/ ModalContainer handles the rendering of modals /}



);
}

export default App;
`

---

$3

!image

> Implemented and integrated with MUI Dialog

A modal is a dialog that provides a flexible way to display content in an overlay. modal can requires the user to interact with it before they can return to the main content. It’s useful for alerting users, asking for confirmation, or gathering information.

#### Basic Usage Example

`tsx
import React from 'react';
import { Button, ThemeProvider } from '@mui/material';
import { ModalContainer, pushModal } from 'react-material-overlay';

const SomeComponent = React.lazy(() => import('./SomeComponent'));

const App = () => {
return (
your application theme/}>
onClick={() => {
pushModal(, {
/modal options/
});
}}
>
open new modal


default options for all modals that push in this container/} />

);
};
`

---

$3

!image

> Implemented and integrated with MUI Dialog

Alerts are urgent interruptions, requiring acknowledgement, that inform the user about a situation.

Most alerts don't need titles. They summarize a decision in a sentence or two by either:

Asking a question (for example "Delete this conversation?")
Making a statement related to the action buttons
Use title bar alerts only for high-risk situations, such as the potential loss of connectivity. Users should be able to understand the choices based on the title and button text alone.

If a title is required:

Use a clear question or statement with an explanation in the content area, such as "Erase USB storage?".
Avoid apologies, ambiguity, or questions, such as "Warning!" or "Are you sure?"

#### Basic Usage Example

`tsx
import React from 'react';
import { Button, ThemeProvider } from '@mui/material';
import { AlertDialogContainer, pushAlertDialog } from 'react-material-overlay';

const App = () => {
return (
your application theme/}>
onClick={() => {
pushAlertDialog({
title: "Use Google's location service?",
content:
'Let Google help apps determine location. This means sending anonymous location data to Google, even when no apps are running.',
onConfirmOk: () => {
console.log('user confirmed ok');
},
onConfirmCancel: () => {
console.log('user confirmed cancel');
}
/other alert dialog options/
});
}}
>
open new alert dialog


default options for all alert dialogs that push in this container/} />

);
};
`

---

$3

!yarl

> Implemented and integrated with yet-another-react-lightbox based on _MUI Theme_.

Lightbox is perfect for displaying image and video galleries in a focused overlay. They are an effective tool for showcasing visual media in a web-friendly, user-engaging, and professional manner.

#### Basic Usage Example

`tsx
import React from 'react';
import { Button, ThemeProvider } from '@mui/material';
import { LightboxContainer, pushLightbox } from 'react-material-overlay';


const App = () => {
return (
your application theme/}>
onClick={() => {
pushLightbox({ slides: [{type: 'image', src: "img source"}, {type: 'video', sources: {/video sources/}}}] /other lightbox options/ });
}}
>
open lightbox


default options for lightbox that push in this container/} />

);
};
`

---

$3

!rsbs

> Implemented and integrated with react-spring-bottom-sheet based on _MUI Theme_.

Bottom sheets slide up from the bottom of the screen, providing contextual or additional information without taking the user away from their current task. Common use cases include action sheets, menus or displaying information in mobile interfaces.

#### Basic Usage Example

`tsx
import React from 'react';
import { Button, ThemeProvider } from '@mui/material';
import { pushBottomSheet, BottomSheetContainer } from 'react-material-overlay';

const SomeComponent = React.lazy(() => import('./SomeComponent'));

const App = () => {
return (
your application theme/}>
onClick={() => {
pushBottomSheet(, {
/ bottom sheet options /
});
}}
>
open new bottom sheet


default options for all bottom sheets that push in this container /} />

);
};
`

---

$3

- pop: You can manually close an overlay by using the pop method or allowing the user to close it via UI elements like backdrop clicks.
- flush: To close all overlays at once, use the flush method.

#### Example

`tsx
import { flush, pop } from 'react-material-overlay';

const App = () => {
return (
pop()}>Close The Last Overlay
pop({ id: 'custom-id' })}>Close The Last Overlay With Id Check
pop(2)}>Close The Last Two Overlays
flush()}>Close All Overlays
);
}
`

---

Custom Overlays

For cases where you want to have your own custom overlay and use the stacking features, browser history sync and etc. you can easily do this using RmoStack.

$3

`tsx
import React from 'react';
import { Button, Drawer } from '@mui/material';
import { RmoStack } from 'react-material-overlay';

const App = () => {
const [openDrawer, setOpenDrawer] = React.useState(false);

return (

);
};
`

---

Caveats

> attention:
> Avoid navigating in the app when you have at least one overlay open.

If you have to navigating when at least one overlay open, first make sure all overlays are closed and then navigate.
To do this, you should call close handlers first, and when the promise is resolved, navigate.

#### With overlay close handler

`tsx
import { Button, ThemeProvider } from '@mui/material';
import { IModalContentProps, ModalContainer, pushModal } from 'react-material-overlay';
import { useNavigate } from 'react-router';

function SomeComponent({ closeModal }: IModalContentProps) {
// note that in such a case of use, ModalContainer must be wrapped with react router provider
const navigate = useNavigate();

return (
onClick={() => {
closeModal().then(() => {
navigate('/some-path');
});
}}
>
close modal and navigate

);
}

const App = () => {
return (

onClick={() => {
pushModal();
}}
>
open new modal




);
};
`

$3

`tsx
import { pop, flush } from 'react-material-overlay';

pop(2).then(() => {
navigate('/some-path');
});

flush().then(() => {
navigate('/some-path');
});
`

---

API Reference

$3

#### options

| Property | Type | Default | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| containerId | Id (optional) | — | Container ID to manage multiple containers. |
| modalId | Id (optional) | — | Custom ID for the modal to prevent duplication. |
| title | React.ReactNode (optional) | — | Title of the modal. |
| subheader | React.ReactNode (optional) | — | Subheader title of the modal. |
| onOpen | () => void (optional) | — | Called when the modal is mounted. |
| onClose | () => void (optional) | — | Called when the modal is unmounted. |
| classes | DialogProps['classes'] \| ((defaultClasses: DialogProps['classes']) => DialogProps['classes']) | — | Override or extend the styles applied to the component. Can merge or overwrite default classes defined in the container. |
| TransitionComponent | DialogProps['TransitionComponent'] (optional) | Fade | The component used for the transition. Refer to the transition component guide. |
| slots | DialogProps['slots'] (optional) | {} | Components used for each slot inside the modal. |
| slotProps | DialogProps['slotProps'] (optional) | {} | Props used for each slot inside the modal. |
| fullScreen | boolean (optional) | false | If true, the dialog is full-screen. |
| fullWidth | boolean (optional) | false | If true, the dialog stretches to the maximum width. |
| maxWidth | Breakpoint \| false (optional) | 'sm' | Determines the max-width of the dialog. Can be 'xs', 'sm', 'md', 'lg', 'xl', or false to disable. |
| PaperComponent | DialogProps['PaperComponent'] (optional) | Paper | The component used to render the body of the dialog. |
| PaperProps | DialogProps['PaperProps'] (optional) | {} | Props applied to the Paper element. |
| scroll | 'body' \| 'paper' (optional) | 'paper' | Determines the container for scrolling the dialog. |
| sx | DialogProps['sx'] (optional) | — | System prop for defining additional CSS styles. |
| transitionDuration | DialogProps['transitionDuration'] (optional) | — | Duration for the transition, in milliseconds. Can be a single value or an object. |
| closeButton | boolean \| ((props: ICloseButtonProps) => React.ReactNode) \| React.ReactElement (optional) | true | Custom close button. Pass false to remove it. Defaults to IconButton. |
| closeButtonProps | IconButtonProps (optional) | — | Props applied to the close button element. Refer to the IconButton props for more details. |
| closeButtonIcon | React.ReactNode \| ((props: Pick) => React.ReactNode) (optional) | — | Custom icon for the close button. |
| raw | boolean (optional) | false | If true, only the content is displayed raw in the modal. |
| transitionPreset | 'zoom' \| 'fade' \| 'grow' \| 'slide' \| 'collapse' (optional) | 'fade' | Adjusts the transition using preset transitions. For more customization, use TransitionComponent. |
| transitionProps | Omit (optional) | — | Props applied to the transition element. Applies to both the transition preset and TransitionComponent. |
| closeOnBackdropClick | boolean (optional) | true | If true, the modal closes when the backdrop is clicked. |
| DialogProps | DialogProps (optional) | — | Props for the Dialog component for further customization. Refer to the Dialog props for details. |
| header | boolean \| ((params: IModalHeaderProps) => React.ReactNode) \| React.ReactElement (optional) | true | Custom header for the modal. Defaults to CardHeader. |
| headerProps | CardHeaderProps (optional) | — | Props for the header component. Refer to the CardHeader props for more details. |
| contentWrapper | boolean \| ((params: IBottomSheetContentWrapperProps) => React.ReactNode) \| React.ReactElement (optional) | true | Pass a custom content wrapper or false to remove wrapper |
| contentWrapperProps | BoxProps (optional) | — | Props for the content wrapper component. Refer to the Box props for details. |
| reactSuspenseFallback | React.ReactNode (optional) | — | Custom React Suspense fallback UI for lazy-loaded contents. |

#### ModalContainer props

| Property | Type | Description |
| ---------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| containerId | Id (optional) | Set an ID to handle multiple modal containers. This allows for differentiation between various instances of modal containers when they are being managed or referenced. |
| defaultOptions | IModalDefaultOptions (optional) | Set default options for modals. This allows you to define common configuration settings that will apply to all modals managed by this container, ensuring consistency and reducing repetitive code. |

#### pushModal API

Opens a new modal overlay. If the container is not mounted or if the modal is a duplicate, it returns null.

##### Parameters

- content (ModalContent): The content to be displayed in the modal. This can be of various types defined in the ModalContent union type.

- options (IModalOptions, optional): Additional options for configuring the modal. This is an object that can contain various properties as specified in the IModalOptions type.

##### Returns

- Promise: A promise that resolves to the modal ID if the modal is successfully opened; otherwise, it resolves to null.

##### Example

`typescript
import { pushModal } from 'react-material-overlay';

const modalId = await pushModal('content');
`

---

$3

#### options

| Property | Type | Default | Description |
| -------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------- |
| containerId | Id (optional) | - | Container ID to handle multiple containers. |
| alertDialogId | Id (optional) | - | Set a custom alertDialogId to prevent duplication. |
| content | React.ReactNode (optional) | - | Content of the alert dialog. |
| title | React.ReactNode (optional) | - | Title of the alert dialog. |
| onConfirmCancel | () => void (optional) | - | Called when the cancel button is clicked. |
| onConfirmOk | () => void (optional) | - | Called when the OK button is clicked. |
| confirmOkText | string (optional) | "ok" | Label for the OK action button. |
| confirmOkButtonProps | ButtonProps (optional) | - | Props for the OK button for further customization. |
| confirmCancelText | string (optional) | "cancel" | Label for the cancel action button. |
| confirmCancelButtonProps | ButtonProps (optional) | - | Props for the cancel button for further customization. |
| actionButtons | ((props: IActionButtonsProps) => React.ReactNode) \| React.ReactElement (optional) | - | Pass custom Dialog Actions. By default, actions are OK and cancel. |
| onOpen | () => void (optional) | - | Called when the modal is mounted. |
| onClose | () => void (optional) | - | Called when the modal is unmounted. |
| DialogTitleProps | DialogTitleProps (optional) | - | Props for the DialogTitle component. |
| DialogContentProps | DialogContentProps> (optional) | - | Props for the DialogContent component. |
| DialogActionsProps | DialogActionsProps> (optional) | - | Props for the DialogActions component. |
| reactSuspenseFallback | React.ReactNode (optional) | - | Set a custom React Suspense fallback UI instead of the default for lazy contents. |
| classes | DialogProps['classes'] \| ((defaultClasses: DialogProps['classes']) => DialogProps['classes']) (optional) | - | Override or extend the styles applied to the component. |
| TransitionComponent | DialogProps['TransitionComponent'] (optional) | Fade | The component used for the transition. Follow the guide to learn more about the requirements for this component. |
| slots | DialogProps['slots'] (optional) | {} | The components used for each slot inside the Modal. |
| slotProps | DialogProps['slotProps'] (optional) | {} | The props used for each slot inside the Modal. |
| fullScreen | boolean (optional) | false | If true, the dialog is full-screen. |
| fullWidth | boolean (optional) | false | If true, the dialog stretches to maxWidth. |
| maxWidth | Breakpoint \| false (optional) | 'sm' | Determine the max-width of the dialog. |
| PaperComponent | DialogProps['PaperComponent'] (optional) | Paper | The component used to render the body of the dialog. |
| PaperProps | DialogProps['PaperProps'] (optional) | {} | Props applied to the Paper element. |
| scroll | 'body' \| 'paper' (optional) | 'paper' | Determine the container for scrolling the dialog. |
| sx | DialogProps['sx'] (optional) | - | The system prop that allows defining system overrides as well as additional CSS styles. |
| transitionDuration | DialogProps['transitionDuration'] (optional) | — | The duration for the transition, in milliseconds. |
| transitionPreset | 'zoom' \| 'fade' \| 'grow' \| 'slide' \| 'collapse' (optional) | 'fade' | Adjust the transition with preset Transitions. If you want more customization, use TransitionComponent prop. |
| transitionProps | Omit (optional) | - | Props applied to the transition element. |
| closeOnBackdropClick | boolean (optional) | true | If true, the modal will close when the backdrop is clicked. |
| DialogProps | DialogProps (optional) | - | Props for the Dialog component for further customization. |

#### AlertDialogContainer props

| Property | Type | Description |
| ---------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| containerId | Id (optional) | An optional identifier for the container, useful for managing multiple alert dialog containers. The Id type represents a unique identifier that can be either a string or a number. |
| defaultOptions | IAlertDialogDefaultOptions (optional) | An optional object that defines default options for all alert dialogs rendered within this container. This allows for consistent behavior across multiple dialogs, such as title, message, buttons, and styles. |

#### pushAlertDialog API

Opens a new alert dialog overlay. If the container is not mounted or if the alert dialog is a duplicate, it returns null.

##### Parameters

- options (IAlertDialogOptions): Configuration options for the alert dialog. This includes properties such as title, content, and actions.

##### Returns

- Promise: A promise that resolves to the alert dialog ID if the alert dialog is successfully opened; otherwise, it resolves to null.

##### Example

`typescript
import { pushAlertDialog } from 'react-material-overlay';

const alertDialogId = await pushAlertDialog({ title: 'Dialog Title', content: 'Dialog Content' });
`

---

$3

#### options

| Property | Type | Default | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| slides | LightboxProps['slides'] | - | Slides to display in the lightbox. This property is required. |
| containerId | Id (optional) | - | Container ID to handle multiple lightbox containers. |
| lightboxId | Id (optional) | "lightbox-overlay" | Custom lightboxId. |
| on | LightboxProps['on'] (optional) | - | Lifecycle callbacks for the lightbox. Can include events like onOpen and onClose. |
| render | LightboxProps['render'] (optional) | - | Custom render functions to control how the lightbox is displayed. |
| labels | LightboxProps['labels'] (optional) | - | Custom UI labels and translations for various elements within the lightbox. |
| toolbarOptions | LightboxProps['toolbar'] (optional) | - | Toolbar settings to customize the appearance and functionality of the lightbox's toolbar. |
| carouselOptions | LightboxProps['carousel'] (optional) | - | Carousel settings to customize the behavior of the lightbox carousel. |
| animationOptions | LightboxProps['animation'] (optional) | - | Animation settings for transitions within the lightbox. |
| controllerOptions | LightboxProps['controller'] (optional) | - | Controller settings for managing user interactions with the lightbox. |
| noScrollOptions | LightboxProps['noScroll'] (optional) | - | Settings for the NoScroll module, which prevents scrolling when the lightbox is open. |
| styles | LightboxProps['styles'] \| ((theme: Theme) => LightboxProps['styles']) (optional) | - | Customization styles for the lightbox. These styles are merged with the default styles defined in the container. |
| captions | boolean (optional) | true | If true, the Captions plugin will be used to display captions for the slides. |
| captionsOptions | LightboxProps['captions'] (optional) | - | Settings for the Captions plugin to customize how captions are displayed. |
| counter | boolean (optional) | false | If true, the Counter plugin will be used to show the current slide number. |
| counterOptions | LightboxProps['counter'] (optional) | - | Settings for the Counter plugin to customize its appearance and behavior. |
| download | boolean (optional) | false | If true, the Download plugin will be used to provide a download option for the slides. |
| downloadOptions | LightboxProps['download'] (optional) | - | Settings for the Download plugin to customize its functionality. |
| fullscreen | boolean (optional) | true | If true, the Fullscreen plugin will be used to allow users to view slides in fullscreen mode. |
| fullscreenOptions | LightboxProps['fullscreen'] (optional) | - | Settings for the Fullscreen plugin to customize how fullscreen mode behaves. |
| share | boolean (optional) | false | If true, the Share plugin will be used to provide sharing options for the slides. |
| shareOptions | LightboxProps['share'] (optional) | - | Settings for the Share plugin to customize sharing functionality. |
| slideshow | boolean (optional) | false | If true, the Slideshow plugin will be used to enable automatic slideshow functionality. |
| slideshowOptions | LightboxProps['slideshow'] (optional) | - | Settings for the Slideshow plugin to customize its behavior. |
| thumbnails | boolean (optional) | true | If true, the Thumbnails plugin will be used to display thumbnails of the slides. |
| thumbnailsOptions | LightboxProps['thumbnails'] (optional) | - | Settings for the Thumbnails plugin to customize how thumbnails are displayed. |
| videoOptions | LightboxProps['video'] (optional) | - | Settings for the Video plugin, which is used by default to handle video content within the lightbox. |
| zoom | boolean (optional) | true | If true, the Zoom plugin will be used to allow users to zoom in on slides. |
| zoomOptions | LightboxProps['zoom'] (optional) | - | Settings for the Zoom plugin to customize its behavior. |
| extraPlugins | LightboxProps['plugins'] (optional) | - | Add extra plugins to enhance the lightbox's functionality. |
| onOpen | () => void (optional) | - | Callback function called when the lightbox is mounted. |
| onClose | () => void (optional) | - | Callback function called when the lightbox is unmounted. |
| className | ((defaultClassName: LightboxProps['className']) => LightboxProps['className']) \| LightboxProps['className'] (optional) | - | Override or extend the styles applied to the component. This can auto merge with the default className or manually overwrite the default className defined in the Container. |

#### LightboxContainer props

| Property | Type | Description |
| ---------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| containerId | Id (optional) | An optional identifier for the lightbox container. This allows for handling multiple instances of lightbox containers. Each container can be uniquely identified using this ID. |
| defaultOptions | ILightboxDefaultOptions | This property sets the default options for the lightbox. It is required and should define various configurations such as animation, duration, and other preferences for the lightbox's appearance and behavior. |

#### pushLightbox API

Opens a new lightbox overlay. If the container is not mounted or if the lightbox is a duplicate, it returns null.

##### Parameters

- options (ILightboxOptions, optional): Additional options for configuring the lightbox, including slides and transition settings.

##### Returns

- Promise: A promise that resolves to the lightbox ID if the lightbox is successfully opened; otherwise, it resolves to null.

##### Example

`typescript
import { pushLightbox } from 'react-material-overlay';

const lightboxId = await pushLightbox({ slides: [...] });
`

---

$3

#### options

| Property | Type | Default | Description |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| containerId | Id (optional) | - | Container ID to manage multiple containers. |
| bottomSheetId | Id (optional) | - | Custom bottomSheetId to prevent duplication. |
| title | React.ReactNode (optional) | — | Title of the bottomSheet. |
| subheader | React.ReactNode (optional) | — | Subheader title of the bottomSheet. |
| closeButton | boolean \| ((props: ICloseButtonProps) => React.ReactNode) \| React.ReactElement (optional) | true | Custom close button. Pass false to remove it. Defaults to IconButton. |
| closeButtonProps | IconButtonProps (optional) | — | Props applied to the close button element. Refer to the IconButton props for more details. |
| closeButtonIcon | React.ReactNode (optional) | — | Custom icon for the close button. |
| onOpen | () => void (optional) | - | Callback function called when the bottom sheet is mounted. |
| onClose | () => void (optional) | - | Callback function called when the bottom sheet is unmounted. |
| className | BottomSheetProps['className'] (optional) | - | CSS class for the BottomSheet root element. Merges with the default className defined in Container or can overwrite it manually. |
| sibling | boolean \| React.ReactNode \| ((props: BottomSheetSiblingProps) => React.ReactNode) (optional) | - | Similar to children, renders next to the overlay element rather than inside it. Useful for position: fixed elements that need to overlay the backdrop while remaining interactive in blocking mode. |
| footer | boolean \| React.ReactNode \| ((props: BottomSheetFooterProps) => React.ReactNode) (optional) | - | Renders a sticky footer at the bottom of the sheet. |
| ref | ForwardedRef (optional) | - | Reference to the BottomSheet. Example: const sheetRef = useRef(); |
| BottomSheetProps | React.PropsWithoutRef (optional) | - | Props for the BottomSheet component (root element) for further customization. |
| sx | SxProps (optional) | - | Allows defining additional CSS styles for the root element. |
| onSpringStart | (event: SpringEvent) => void (optional) | - | Called to start a transition from closed to open or vice versa. Can return a promise or be async to delay the start of the transition. |
| onSpringCancel | (event: SpringEvent) => void (optional) | - | Event that occurs when a running transition didn't finish or got stopped. This event isn't awaited and may happen after the sheet is unmounted if it were in the middle of something. |
| onSpringEnd | (event: SpringEvent) => void (optional) | - | Called when the transition ended successfully. Useful for knowing when it's safe to unmount the sheet without interrupting the closing animation. Can return a promise or be async to delay the start of the transition. |
| initialFocusRef | React.RefObject \| false (optional) | - | Reference to the element that should be focused. Defaults to the first interactive element. Set to false to disable keyboard focus when opening. |
| blocking | boolean (optional) | true | Determines whether the bottom sheet should block interactions with the rest of the page. |
| maxHeight | number (optional) | window.innerHeight | The maximum height, defaults to window.innerHeight to match 100vh. Can be overridden by providing a number. Ensure to handle resize events when needed. |
| scrollLocking | boolean (optional) | true | Ensures drag interactions work properly on iOS and Android. If set to false, test on actual devices to ensure dragging interactions don't break. |
| snapPoints | snapPoints (optional) | ({ minHeight }) => minHeight | Callback to get height values that the bottom sheet can snap to when the user stops dragging. |
| defaultSnap | number \| ((props: defaultSnapProps) => number) (optional) | ({ snapPoints, lastSnap }) => lastSnap ?? Math.min(...snapPoints) | Callback to get the initial height of the bottom sheet when opened or when the viewport is resized. |
| reserveScrollBarGap | boolean (optional) | blocking === true | Configures body-scroll-lock to reserve scrollbar gap by setting padding on , cleared when closing the bottom sheet. Defaults to true if blocking is true. |
| skipInitialTransition | boolean (optional) | false | Open immediately instead of animating from a closed to open state. Useful if the bottom sheet is visible by default. |
| header | boolean \| ((params: IBottomSheetHeaderProps) => React.ReactNode) \| React.ReactElement (optional) | true | Renders below the drag handle. Set to false to disable the drag handle. |
| defaultHeader | boolean (optional) | true | if true defaultheader element will be rendered |
| headerProps | CardHeaderProps` (optional)