react-modal-minimal

Accessible React modal dialog component. Controlled via props, with overlay, close button, keyboard support, and focus management.

The package styles the modal shell (overlay, panel, optional header, close button). Content styling is left to the consumer.

Installation

npm install react-modal-minimal

Or with Yarn:

yarn add react-modal-minimal

Peer dependencies (must be installed in your app):

npm install react react-dom
# or
yarn add react react-dom

Import the compiled styles once in your application:

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

Usage

Basic example without a title:

import { useState } from 'react';
import { Modal } from 'react-modal-minimal';
import 'react-modal-minimal/style.css';

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button type="button" onClick={() => setIsOpen(true)}>
        Open modal
      </button>

      <Modal
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        ariaLabel="Confirmation"
      >
        <p style={{ margin: 0, paddingBlock: '1rem', textAlign: 'center' }}>
          Operation completed.
        </p>
      </Modal>
    </>
  );
}

With an optional title:

<Modal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  title="Success"
>
  <p>Your changes have been saved.</p>
</Modal>

Styling content

Typography, alignment, and spacing of children are the consumer's responsibility. Use your own CSS classes, CSS Modules, or inline styles:

<Modal isOpen={isOpen} onClose={close} ariaLabel="Confirmation">
  <p className={styles.message}>Operation completed.</p>
</Modal>

When title is omitted, no header block is rendered — only the close button and your content appear inside the panel.

Props

| Prop | Type | Required | Description | |------|------|:--------:|-------------| | isOpen | boolean | Yes | Controls modal visibility. When false, nothing is rendered. | | onClose | () => void | Yes | Called when the user closes the modal (overlay click, Escape key, or close button). | | children | ReactNode | Yes | Content rendered inside the modal panel. | | title | string | No | Optional heading shown in the modal header. When omitted, no header block is rendered. | | ariaLabel | string | No | Accessible name when title is omitted. Defaults to "Dialog". Sets aria-label on the dialog. |

Behavior

• Controlled component — the parent owns isOpen state; onClose is a callback only.
• Close triggers — overlay click, Escape key, or × button.
• Body scroll lock — page scrolling is disabled while the modal is open.
• Focus management — focus moves into the modal on open and returns to the previous element on close.
• Focus trap — Tab and Shift+Tab cycle within focusable elements inside the panel.

Accessibility

• role="dialog" and aria-modal="true" on the panel
• aria-labelledby when title is provided
• aria-label (via ariaLabel) when title is omitted
• Close button exposes aria-label="Close modal"
• Keyboard: Escape to close, Tab cycle within the dialog

Local development

Clone the repository, install dependencies, and run the demo:

npm install
npm run dev      # http://localhost:5173
npm run build    # outputs dist/
npm run lint     # ESLint (hooks, a11y, recommended)

Or with Yarn:

yarn
yarn dev
yarn build
yarn lint

To use the package locally in another project during development:

# In this package
npm run build
npm link

# In your app
npm link react-modal-minimal

With Yarn:

# In this package
yarn build
yarn link

# In your app
yarn link react-modal-minimal

Or reference it with a local path:

{
  "dependencies": {
    "react-modal-minimal": "file:../path/to/react-modal-minimal"
  }
}

Rebuild the package after changing source or styles:

npm run build
# or
yarn build

Build output

• dist/index.js — ESM entry (import { Modal } from 'react-modal-minimal')
• dist/style.css — compiled shell styles (import 'react-modal-minimal/style.css')

License

MIT