The Modern React Modal Library

A lightweight, promise-based modal component for React that makes handling modals simple, intuitive, and type-safe.

Installation

Features

React Snappy Modal is designed to make modal management simple and intuitive with a powerful promise-based API.

Promise-based API

Use async/await with your modals to handle user interactions in a clean, sequential way without callback hell.

Lightweight

Zero dependencies and tiny bundle size to keep your application fast and performant.

Customizable

Easily customize the appearance and behavior of your modals with simple configuration options.

Type Safe

Built with TypeScript to provide excellent type checking and IntelliSense support.

Controlled Flow

Control the flow of your application by waiting for user input before proceeding with the next steps.

React 18+ Compatible

Built to work perfectly with the latest versions of React, including concurrent rendering.

Examples

See React Snappy Modal in action with these common modal patterns

Alert Modal

Simple alert modals can be used to display information to the user. The modal returns a promise that resolves when the user closes it.

tsx

1function AlertModal() {
2  return (
3    <ModalWrapper>
4      <ModalTitle>Alert</ModalTitle>
5      <ModalText>
6        This is a simple alert modal that displays information to the user.
7      </ModalText>
8      <ModalButtons>
9        <ModalButton primary onClick={() => SnappyModal.close()}>
10          Confirm
11        </ModalButton>
12      </ModalButtons>
13    </ModalWrapper>
14  );
15}
16
17const showAlert = async () => {
18  await SnappyModal.show(<AlertModal />)
19  alert("alert closed")
20};
21

Confirmation Modal

Confirmation modals let users make decisions. The modal returns the value passed to SnappyModal.close(), making it easy to handle user choices.

tsx

1function ConfirmModal() {
2  return (
3    <ModalWrapper>
4      <ModalTitle>Confirm Action</ModalTitle>
5      <ModalText>Are you sure you want to proceed?</ModalText>
6      <ModalButtons>
7        <ModalButton onClick={() => SnappyModal.close(false)}>
8          Cancel
9        </ModalButton>
10        <ModalButton primary onClick={() => SnappyModal.close(true)}>
11          Confirm
12        </ModalButton>
13      </ModalButtons>
14    </ModalWrapper>
15  );
16}
17
18const showConfirm = async () => {
19  const result = await SnappyModal.show(<ConfirmModal />);
20  alert("User confirmed:" + result);
21
22  if (result) {
23    // User confirmed
24  } else {
25    // User cancelled
26  }
27};
28

Form Modal

Easily create modal forms to collect user input. The form data can be passed as the result of the modal, making it simple to process.

tsx

1function FormModal() {
2  const [name, setName] = useState("");
3
4  return (
5    <ModalWrapper>
6      <ModalTitle>Enter Your Name</ModalTitle>
7      <FormGroup>
8        <Label>Full Name</Label>
9        <Input
10          value={name}
11          onChange={e => setName(e.target.value)}
12          placeholder="Enter your full name"
13        />
14      </FormGroup>
15      <ModalButtons>
16        <ModalButton onClick={() => SnappyModal.close(null)}>
17          Cancel
18        </ModalButton>
19        <ModalButton primary onClick={() => SnappyModal.close(name)}>
20          Submit
21        </ModalButton>
22      </ModalButtons>
23    </ModalWrapper>
24  );
25}
26
27const showForm = async () => {
28  const result = await SnappyModal.show(<FormModal />);
29  
30  if (result) {
31    alert("Submitted name:" + result);
32  }
33};
34

Installation

Get started with React Snappy Modal in just a few simple steps

bash

1npm install react-snappy-modal

Install the package

Install the react-snappy-modal package using your preferred package manager as shown above.

Import the modal component

Import the SnappyModal component in your application.

tsx

1import SnappyModal from 'react-snappy-modal';

Add the SnappyModalProvider

Wrap your application with the SnappyModalProvider to ensure modals can be displayed anywhere in your app.

tsx

1import { SnappyModalProvider } from 'react-snappy-modal';
2
3function App() {
4  return (
5    <SnappyModalProvider>
6      {/* Your app components */}
7    </SnappyModalProvider>
8  );
9}

Start using modals

You're all set! Now you can use SnappyModal.show() anywhere in your application to display modals.

Usage

Learn how to effectively use React Snappy Modal in your application

Basic Usage

React Snappy Modal provides a simple, promise-based API for displaying modals. Here's a basic example:

tsx

1import React from 'react';
2import SnappyModal from 'react-snappy-modal';
3
4function MyComponent() {
5  const showModal = async () => {
6    const result = await SnappyModal.show(
7      <div className="my-modal">
8        <h2>My Modal</h2>
9        <p>This is a basic modal example.</p>
10        <button onClick={() => SnappyModal.close('modal result')}>
11          Close Modal
12        </button>
13      </div>
14    );
15    
16    console.log('Modal result:', result);
17  };
18
19  return (
20    <button onClick={showModal}>Open Modal</button>
21  );
22}

Configuring Modal Options

You can customize the behavior and appearance of your modals with various options:

tsx

1// Show a modal with custom options
2const showCustomModal = async () => {
3  const result = await SnappyModal.show(
4    <div className="my-modal">
5      <h2>Custom Modal</h2>
6      <p>This modal has custom options.</p>
7      <button onClick={() => SnappyModal.close('result')}>
8        Close
9      </button>
10    </div>,
11    {
12      // Modal configuration options
13      allowOutsideClick: false,  // Prevent closing when clicking backdrop
14      allowScroll: true,         // Allow page scrolling behind modal
15      backdrop: 'rgba(0,0,0,0.8)', // Custom backdrop color
16      position: 'top-center',    // Position modal at top
17      zIndex: 1050              // Custom z-index
18    }
19  );
20  
21  console.log('Modal closed with:', result);
22};

API Reference

Option	Description
SnappyModal.show(component, options?)	Displays a modal containing the provided React component. Returns a Promise that resolves with the value passed to SnappyModal.close().
SnappyModal.close(value?)	Closes the currently open modal and resolves the promise returned by SnappyModal.show() with the provided value.
SnappyModal.throw(error?)	Closes the modal and rejects the promise with the provided error. Useful for handling cancellation or error states.
SnappyModal.isShow()	Returns a boolean indicating whether a modal is currently displayed.

Options

Option	Type	Default	Description
allowOutsideClick	boolean	true	When true, clicking outside the modal will close it.
allowScroll	boolean	false	When true, the page behind the modal can be scrolled.
backdrop	boolean \| string	true	Controls the modal backdrop. Set to false to hide backdrop, true for default backdrop, or a string CSS color value for a custom color.
position	string	'center'	Position of the modal. Options: 'top-left', 'top-center', 'top-right', 'center-left', 'center', 'center-right', 'bottom-left', 'bottom-center', 'bottom-right'.
zIndex	number	1000	Z-index for the modal and backdrop.