React Floating Modals

This library was created as a small and reusable module to streamline usually tedious and long process of creating floating modals.

key features:

• zero-dependency (except React itself of course) window library for React 18+.
• Pointer-Events drag – smooth on mouse, touch & pen.
• Headless styling – bring your own CSS or Tailwind; nothing is hard-coded.
• Window manager – one context handles z-index and cleanup.
• Tiny bundle – no external libraries, tree-shakeable.
• 100 % TypeScript – autocompletion for every prop & hook.

Installation

npm i react-floating-modals          # or pnpm add / yarn add

Peer dependencies: react >= 18, react-dom >= 18.

Quick start

import {
  WindowManagerProvider,
  useWindowManager,
  FloatingModal
} from 'react-floating-modals';

function App() {
  return (
    <WindowManagerProvider>
      <LauncherButton />
    </WindowManagerProvider>
  );
}

function LauncherButton() {
  const wm = useWindowManager();

  return (
    <button onClick={() => wm.spawn(<MyWindow />)}>
      Open window
    </button>
  );
}

function MyWindow({ windowId }: { windowId?: number }) {
  const wm = useWindowManager();

  return (
    <div className="my-window">
      <header data-drag-handle>
        Drag me!
        <button onClick={() => windowId !== undefined && wm.close(windowId)}>
          ×
        </button>
      </header>
      <main>Any content…</main>
    </div>
  );
}

1. Wrap your app (or a subtree) with <WindowManagerProvider>.
2. Call wm.spawn(<YourComponent />) to open a new window.
3. Inside the window, read windowId and call wm.close(windowId) to dismiss it.
4. Add data-drag-handle to any element (or pass handleSelector prop) to make it draggable.

API reference

<FloatingModal />

| Prop | Type | Default | Description | |------|------|---------|-------------| | initialX | number \| 'center' | 'center' | Starting left (px) or center. | | initialY | number \| 'center' | 'center' | Starting top (px) or center. | | handleSelector | string | '[data-drag-handle]' | CSS selector for the drag handle, searched relative to the modal root. | | onDrag | (coords ⇒ void) | — | Callback on every move { x, y }. | | …div props | — | — | Regular <div> attributes (style, className, etc.). |

Imperative handle

const ref = useRef<FloatingModalHandle>(null);

ref.current?.resetPosition(0, 0);      // snap to top-left
ref.current?.resetPosition('center');  // recenter

<WindowManagerProvider />

Provides a store for all windows.

const wm = useWindowManager();

const id = wm.spawn(<Window />);   // open
// wm.spawn has second optional argument - singleTone=true, if enabled, allows to create only single active instance of the same modal 
wm.focus(id);                      // bring to front
wm.close(id);                      // close
wm.closeAll()                      // close all open windows

Styling

react-floating-modals ships no CSS by default—it’s headless.
Assign your own classes or inline styles. A minimal Tailwind look:

<div className="w-80 bg-white rounded shadow-lg">
  <header
    data-drag-handle
    className="bg-indigo-600 text-white px-4 py-2 rounded-t cursor-move flex justify-between"
  >
    …

License

MIT