epic-modals

A stunning modal library with macOS-style animations, drag, resize, and dock. Supports Svelte 5, React, and vanilla JavaScript.

Live Demo · NPM

Installation

``bash
npm install epic-modals
`

Quick Start

$3

`tsx
import { ModalProvider, Modal, Dock, useModal } from 'epic-modals/react';
import 'epic-modals/styles';

// Modal IDs can be symbols (recommended) or strings
const MODAL_ID = Symbol('my-modal');

function App() {
return (




);
}

function MyComponent() {
const { open, close } = useModal(MODAL_ID);

return (
<>
open(e.currentTarget)}>Open

footer={Close}
>


Your content here!




);
}
`

$3

`svelte



openModal(MODAL_ID, e.currentTarget)}>Open




Your content here!

{#snippet footer()}
closeModal(MODAL_ID)}>Close
{/snippet}




`

$3

`js
import { init, createModal, openModal, closeModal } from 'epic-modals/vanilla';
import 'epic-modals/styles';

// Modal IDs can be symbols (recommended) or strings
const MODAL_ID = Symbol('my-modal');

// Initialize library (creates backdrop + dock automatically)
init();

createModal({
id: MODAL_ID,
title: 'Hello World',
content: '

Your content here!

',
footer: 'Close',
maxWidth: '480px',
});

document.querySelector('#close-btn').onclick = () => closeModal(MODAL_ID);
document.querySelector('#open-btn').onclick = (e) => {
openModal(MODAL_ID, e.currentTarget);
};
`

Features

- Dock - Minimized modals appear in a customizable dock
- Minimize/Restore - Smooth genie animation to/from dock
- Resize - 8-direction resize handles
- Drag - Drag modals by header
- Parent-Child - Modals can spawn child modals
- Attention Effect - Shake animation to grab user attention
- Focus Trap - Tab key stays within modal
- macOS Style - Traffic light buttons (close, minimize, maximize)
- Theming - Light/dark themes + full CSS variable customization

Hooks & Functions

$3

`tsx
import { useModal, useModals } from 'epic-modals/react';

const MODAL_ID = Symbol('my-modal');

function MyComponent() {
const {
open, // (element) => void - Open modal
close, // () => void - Close modal
minimize, // () => void - Minimize to dock
restore, // () => void - Restore from dock
shake, // () => void - Trigger attention effect
bringToFront, // () => void - Focus modal (z-index)
isOpen, // boolean
isMinimized, // boolean
isRegistered, // boolean
} = useModal(MODAL_ID);

return (
open(e.currentTarget)}>Open
);
}
`

$3

`svelte


modal.open(e.currentTarget)}>Open
`

$3

`js
import {
openModal, closeModal, minimizeModal, restoreModal,
triggerAttention, bringToFront, isModalOpen
} from 'epic-modals/vanilla';

const MODAL_ID = Symbol('my-modal');

openModal(MODAL_ID, buttonElement);
closeModal(MODAL_ID);
minimizeModal(MODAL_ID);
restoreModal(MODAL_ID);
triggerAttention(MODAL_ID); // Shake effect
bringToFront(MODAL_ID);
isModalOpen(MODAL_ID); // Returns boolean
`

Parent-Child Modals

`tsx
// React
import { useModal } from 'epic-modals/react';

const PARENT_ID = Symbol('parent');
const CHILD_ID = Symbol('child');

function Parent() {
const parent = useModal(PARENT_ID);
const child = useModal(CHILD_ID);

return (

child.openAsChild(PARENT_ID, e.currentTarget)}>
Open Child


);
}
`

`svelte




openChildModal(CHILD_ID, PARENT_ID, e.currentTarget)}>
Open Child






I'm a child modal!



`

Configuration

`tsx
features: {
dock: true, // Enable dock for minimized modals
minimize: true, // Enable minimize button
resize: true, // Enable resize handles
drag: true, // Enable drag to move
focusTrap: true, // Enable focus trapping
animations: true, // Enable animations
backdrop: true, // Enable backdrop overlay
},
dock: {
position: 'bottom', // 'left' | 'right' | 'bottom'
labelMode: 'hidden', // 'hidden' | 'beside' | 'below'
},
animations: {
open: 400,
close: 250,
minimize: 500,
restore: 400,
},
appearance: {
headerLayout: 'macos', // 'macos' | 'windows' | 'none'
},
}}>
`

Theming

`css
/ Import base styles /
@import 'epic-modals/styles';

/ Optional: Import a theme /
@import 'epic-modals/styles/themes/light';
@import 'epic-modals/styles/themes/dark';
`

Override CSS variables for custom theming:

`css
:root {
--modal-bg: #ffffff;
--modal-border-radius: 12px;
--modal-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
--modal-title-color: #1a1a1a;

/ Traffic lights /
--modal-btn-close: #ff5f57;
--modal-btn-minimize: #febc2e;
--modal-btn-maximize: #28c840;

/ Dock /
--modal-dock-bg: linear-gradient(to bottom, #f8f9fa, #f0f1f3);
}
``

License

Elastic License 2.0 - Free for commercial use, but you cannot offer it as a hosted service or redistribute it as your own product.