React-Modal-Pro

React-Modal-Pro is a versatile and lightweight library for managing modals in React applications. It offers seamless support for dialogs, sidebars, and sheets, giving you full control over their behavior and appearance. With native-like navigation integration, modals can close when navigating back in history, without actually reverting to the previous page—providing a smooth, app-like user experience.

---

Table of Contents

• Key Features
• Installation
• Example: Building Modals with React-Modal-Pro
• Styling & Customization
• Props Reference
• Demo

---

Key Features

• Effortlessly manage multiple modals.
• Native-like modal behavior with history-based closing.
• Swipe-to-open and swipe-to-close functionality for sidebars and sheets.
• Simple yet powerful API for fine-tuned control.

With React-Modal-Pro, creating professional, responsive, and intuitive modals has never been easier.

---

Installation

To install React-Modal-Pro, you can use npm or yarn:

1# Using npm
2$ npm install --save react-modal-pro
3
4# Using yarn
5$ yarn add react-modal-pro

Example: Building Modals with React-Modal-Pro

Below is a simple example demonstrating how to use React-Modal-Pro to create a bottom sheet, a sidebar, and a center dialog, each controlled by unique keys and customizable props.

Highlights:

1. Unique Modal Keys:
   Each modal uses a unique modalKey to ensure smooth and independent functionality, even when managing multiple modals simultaneously.

2. Global Modal Control:
   Using the useModalController hook, you can programmatically control any modal, allowing you to close (or open) it from anywhere in your app.

3. Customizable Props:
   Tailor your modals with a variety of props for direction, triggers, gestures, and more. (Details on all available props are explained later!)

Code Example:

1import React from 'react';
2import ReactDOM from 'react-dom/client';
3import { ProModalProvider, ProSheet, Sidebar, useModalController, Dialog } from 'react-modal-pro';
4
5function App() {
6  return (
7    <div>
8      <BottomSheet />
9      <SidebarLeft />
10      <CenterDialog />
11    </div>
12  );
13}
14
15function BottomSheet() {
16  return (
17    <ProSheet
18      modalKey="bottom-sheet"
19      direction="bottom"
20      TriggerElement={<button>open bottom sheet</button>}
21    >
22      <BottomSheetContent />
23    </ProSheet>
24  );
25}
26
27function BottomSheetContent() {
28  const { handleCloseModal } = useModalController("bottom-sheet");
29  return (
30    <button onClick={handleCloseModal}>
31      click to close bottom sheet with me!
32    </button>
33  );
34}
35
36function SidebarLeft() {
37  return (
38    <Sidebar
39      modalKey="sidebar-left"
40      direction="left"
41      TriggerElement={<button>open sidebar left</button>}
42    >
43      Hey, This is sidebar-left content!
44    </Sidebar>
45  );
46}
47
48function CenterDialog() {
49  return (
50    <Dialog
51      modalKey="dialog"
52      TriggerElement={<button>open dialog</button>}
53    >
54      Hey, This is dialog content!
55    </Dialog>
56  );
57}
58
59const root = ReactDOM.createRoot(document.getElementById("root"));
60root.render(
61  <React.StrictMode>
62    <ProModalProvider>
63      <App />
64    </ProModalProvider>
65  </React.StrictMode>
66);

Key Takeaways

• Unique Keys: Assign a unique modalKey (e.g., 'bottom-sheet', 'sidebar-left') for independent modal control.
• Dynamic Control: Use the useModalController hook to dynamically manage modals, such as closing a modal from within its content using handleCloseModal.
• Customizable Props: Configure modals with props for directions, gestures, animations, and more.

---

Styling & Customization

This library offers extensive styling options through CSS variables, allowing you to customize the appearance of modals and sheets easily. Below is a list of the root styles provided, along with their default values and descriptions:

1:root {
2  --react-modal-pro-sheet-radius: 12px; /* Corner radius for modal sheets */
3  --react-modal-pro-sheet-padding: 24px; /* Inner padding for modal sheets */
4  --react-modal-pro-sheet-background: #ffffff; /* Background color of the modal sheets */
5  --react-modal-pro-backdrop-background: #0000004a; /* Background color of the modal backdrop */
6  --react-modal-pro-dialog-sheet-z-index: 1200; /* Z-index for dialog modal sheets */
7  --react-modal-pro-dialog-backdrop-z-index: 1199; /* Z-index for dialog modal backdrops */
8  --react-modal-pro-sidebar-sheet-z-index: 1000; /* Z-index for sidebar modal sheets */
9  --react-modal-pro-sidebar-backdrop-z-index: 999; /* Z-index for sidebar modal backdrops */
10  --react-modal-pro-pro-sheet-sheet-z-index: 1100; /* Z-index for pro-sheet modal sheets */
11  --react-modal-pro-pro-sheet-backdrop-z-index: 1099; /* Z-index for pro-sheet modal backdrops */
12}

You can override these variables in your global CSS to match your project's design requirements. For example:

1:root {
2  --react-modal-pro-sheet-radius: 16px;
3  --react-modal-pro-backdrop-background: rgba(0, 0, 0, 0.7);
4}

These changes will seamlessly update the modal appearance across your application.

Additional Customization Options

The library also provides several className-based options for styling:

Default Class Names for All Modals

You can specify default class names for all modals by using the defaultSheetClassName and defaultBackdropClassName props when setting up the ProModalProvider. These class names will be applied to all modals within the provider's scope.

Example:

1<ProModalProvider
2  defaultSheetClassName="modal-sheet-root"
3  defaultBackdropClassName="modal-backdrop-root">
4  {children}
5</ProModalProvider>

Per-Modal Class Names

If you want to apply specific class names to individual modals, you can use the sheetClassName and backdropClassName props directly on the modal components (Dialog, ProSheet, Sidebar).

Example with Dialog (works seamlessly for ProSheet and Sidebar):

1<Dialog
2  modalKey="dialog"
3  sheetClassName="dialog-sheet"
4  backdropClassName="dialog-backdrop"
5  TriggerElement={<button>open dialog</button>}>
6  Hey, This is dialog content!
7</Dialog>

Static Class Name for Trigger Element

The library applies a static class name, modal_pro_trigger_element, to the TriggerElement of all modals. This ensures consistent styling across all trigger elements.

Example:

1.modal_pro_trigger_element {
2  cursor: pointer;
3  color: #007bff;
4}

By combining these options, you can achieve a highly customizable and consistent design for your modal components.

---

Props Reference

ProModalProvider Props

Prop	Type	Default	Description
defaultCanDismiss	boolean	true	Allows modals to be dismissed by clicking the backdrop or swiping.
defaultOpenDuration	number	400	Duration (in ms) for opening animations.
defaultCloseDuration	number	300	Duration (in ms) for closing animations.
defaultSheetClassName	string	""	Default class name for the modal sheet.
defaultBackdropClassName	string	""	Default class name for the modal backdrop.

---

Shared Modal Props (Dialog, Sidebar, ProSheet)

Prop	Type	Default	Required	Description
modalKey	string	-	Yes	Unique key for identifying the modal.
children	ReactNode	-	Yes	Content displayed inside the modal.
TriggerElement	ReactNode	-	Yes	Element that triggers modal opening.
canDismiss	boolean	true	No	Allows dismissal by backdrop click.
closeCb	() => void	undefined	No	Callback executed when the modal closes.
closeDuration	number	300	No	Duration (in ms) for closing animations.
openDuration	number	400	No	Duration (in ms) for opening animations.
backdropClassName	string	""	No	Custom class name for the backdrop.
sheetClassName	string	""	No	Custom class name for the modal container.

---

Component-Specific Props

Dialog

Prop	Type	Default	Required	Description
(inherits shared props)	-	-	-	-

Sidebar

Prop	Type	Default	Required	Description
direction	left right	-	Yes	Direction the sidebar opens (left or right).
swipeToOpen	boolean	false	No	Enables swipe-to-open functionality.
swipeToClose	boolean	false	No	Enables swipe-to-close functionality.
swipeThreshold	number	100	No	Threshold for swipe gestures.

ProSheet

Prop	Type	Default	Required	Description
direction	bottom top	-	Yes	Direction the sheet opens (bottom or top).
swipeToOpen	boolean	false	No	Enables swipe-to-open functionality.
swipeToClose	boolean	false	No	Enables swipe-to-close functionality.
swipeThreshold	number	100	No	Threshold for swipe gestures.

---

Demo

Try the live demo on Codesandbox:
https://codesandbox.io/p/devbox/pedantic-lumiere-njcdm6