react-motion-modal

react-motion-modal is a flexible modal management library built with Zustand for state management and powered by Framer Motion for beautiful animations. It offers full TypeScript type-safety and allows dynamic modal opening with custom parameters.

✨ Features

• Stack-based modal management (multiple modals at once)
• Type-safe parameters per modal
• Auto-injection of closeModal() into each modal props
• Full intellisense for modal names and parameters
• Easily extensible via module augmentation

🧱 Installation

npm install react-motion-modal motion zustand

or with yarn:

yarn add react-motion-modal motion zustand

react and react-dom are expected to already exist in your app.

🚀 Usage

1. Import styles

Import the package stylesheet once in your app entry:

import 'react-motion-modal/style.css';

2. Define modal types

Create a modal.d.ts file in your project (make sure to include it in tsconfig.json):

import type { ModalDefinition } from 'react-motion-modal';

declare module 'react-motion-modal' {
  interface ModalDefinition {
    AlertModal: {
        title: string;
    };
    ConfirmModal: {
        onConfirm: () => void;
    };
  }
}

3. Import

Import to define your modals

import { ModalProvider } from 'react-motion-modal';

export const App = () => {
   return (
      <div>
         {/* rest of your app */}

         <ModalProvider
            modals={{
               AlertModal,
               ConfirmModal,
            }}
         />
      </div>
   );
};

4. Open modal anywhere

import { MODAL_POSITIONS, modalStore } from 'react-motion-modal';

const { openModal } = modalStore();

openModal('ConfirmModal', {
   title: 'Are you sure you want to delete?',
   position: MODAL_POSITIONS.RIGHT,
   closeOnClickOutside: true,
});

5. Use closeModal inside your modal component

import type { ModalParams } from 'react-motion-modal';

const ConfirmModal = ({ title, closeModal }: ModalParams<'ConfirmModal'>) => (
   <div>
      <h1>{title}</h1>
      <button onClick={closeModal}>Close</button>
   </div>
);

🧩 API

openModal(name, params)

Opens a modal by name. The params will be inferred based on modal type.

closeModal(name?)

• If name is provided, closes that specific modal.
• If not, closes the most recent modal (top of the stack).

BaseModalParams

Each modal automatically receives the following props:

| Prop | Type | Description | |-----------------------|------------------------------------------------------------------|-------------------------------------------------------------------------------| | closeModal | () => void | Close function for the modal | | onClose | () => void | Callback triggered when modal is closed | | closeOnClickOutside | boolean | Close modal when clicking outside | | closeOnPressEsc | boolean | Close modal when Escape key is pressed | | position | string | Modal placement. Unknown values fall back to center. | | backdrop | { className?: string; style?: CSSProperties; } | Customize the backdrop layer | | body | { className?: string; style?: CSSProperties; } | Customize the modal body wrapper | | animate | { animate?: TargetAndTransition; exit?: TargetAndTransition; } | Animation powered by Framer Motion. Custom animation disables defaults. | | blur | boolean | Apply backdrop blur |

MODAL_POSITIONS

MODAL_POSITIONS.TOP;
MODAL_POSITIONS.TOP_LEFT;
MODAL_POSITIONS.TOP_RIGHT;
MODAL_POSITIONS.TOP_CENTER;
MODAL_POSITIONS.LEFT;
MODAL_POSITIONS.RIGHT;
MODAL_POSITIONS.CENTER;
MODAL_POSITIONS.CENTER_FULL;
MODAL_POSITIONS.BOTTOM;
MODAL_POSITIONS.BOTTOM_LEFT;
MODAL_POSITIONS.BOTTOM_RIGHT;
MODAL_POSITIONS.BOTTOM_CENTER;

Default body animation follows the position. For example, left slides in from the left, right slides in from the right, top slides down, and bottom slides up.

🔐 Release Security

• CI runs from .github/workflows/ci.yml on pushes and pull requests.
• npm publishing is defined in .github/workflows/publish.yml and uses npm publish --provenance --access public.
• Trusted publishing still needs to be enabled in npm package settings for this repository before the workflow can publish official releases.

📝 Notes

• Zustand-based, framework-agnostic state management
• Built-in animation system powered by Framer Motion
• You can implement a ModalRenderer to dynamically render modals from modals state
• Great for complex apps requiring nested or dynamic modal stacks

Made with ❤️ by react-motion-modal.