Accessible modal & dialog engine with focus trapping, scroll lock, stacking layers, and a catalog of backdrop styles (dim, blur, glass, gradient).
<link rel="stylesheet" href="https://cdn.get-set.it/gs-modal/latest/gs-modal.min.css"> <script src="https://cdn.get-set.it/gs-modal/latest/gs-modal.min.js"></script>
import Modal from '@get-set/gs-modal'; export default function App() { return ( <Modal> <div className="content">Your Modal content</div> </Modal> ); }
This is a real GSModal running your current option set — animation, backdrop, position, size…
| Option | Type | Default | Description |
|---|---|---|---|
| reference | string | none | Reference. |
| closeOnBackdrop | boolean | true | Close when the backdrop (area outside the dialog) is clicked. Default: true. |
| closeOnEsc | boolean | true | Close when Escape is pressed (topmost modal only). Default: true. |
| animation | GSModalAnimation | false | 'zoom' | Entrance animation name from the catalog. `false` disables all dialog motion. Default: 'zoom'. |
| exitAnimation | GSModalAnimation | false | none | Separate exit animation name. Defaults to mirroring `animation` when omitted. `false` disables exit motion. |
| animationDuration | number | { enter?: number; exit?: number } | 250 | Animation duration in ms. A number applies to both enter and exit; an object sets each independently. Default: 250. |
| animationEasing | string | 'cubic-bezier(.34,1.56,.64,1)' | CSS easing applied to the dialog enter/exit animation. |
| backdropAnimation | GSModalAnimation | false | 'fade' | Backdrop's own animation (independent of the dialog). Default: 'fade'. |
| backdropAnimationDuration | number | none | Backdrop fade duration in ms. Default: 200. |
| reducedMotion | 'auto' | boolean | 'auto' | Honor `prefers-reduced-motion`. `'auto'` follows the OS setting; `true` always reduces; `false` never reduces. Default: 'auto'. |
| title | string | none | Optional header title. When set, renders a header and wires aria-labelledby. |
| subtitle | string | none | Secondary line shown under the title in the header. |
| footer | string | false | none | Footer area content. `false` (default) = no footer. |
| size | ModalSize | 'md' | Dialog size preset. Default: 'md'. |
| width | number | string | none | Explicit width (overrides `size`). Number = px. |
| height | number | string | none | Explicit height. Number = px. |
| maxWidth | number | string | none | Clamp width on small viewports. Default: 92vw. |
| maxHeight | number | string | none | Clamp height; body becomes scrollable past this. Default: 90vh. |
| minWidth | number | string | none | Lower bound on width. |
| minHeight | number | string | none | Lower bound on height. |
| fullscreen | boolean | false | Always full-viewport (no rounded corners, no margins). Default: false. |
| fullscreenBelow | FullscreenBreakpoint | false | Render full-screen when the viewport width is at or below the breakpoint (Bootstrap `modal-fullscreen-*-down` parity). `number` = px. Default: false. |
| position | GSModalPosition | 'center' | Dialog position preset. Default: 'center'. |
| offset | GSModalOffset | none | Custom nudge from the resolved position. |
| backdrop | boolean | 'static' | true | Backdrop mode. `true` = dimmed, click-to-close. `false` = no overlay. `'static'` = overlay present but click does not close (plays a shake). |
| backdropColor | string | none | Overlay color. Default: rgba(17,24,39,.55). |
| backdropOpacity | number | none | Overlay opacity (0–1). Applied as the overlay's alpha. |
| backdropBlur | boolean | number | string | false | Backdrop blur. `true`=8px; number=px; string=raw CSS length. Default: false. |
| backdropType | GSModalBackdropType | none | Rich backdrop layer preset (gradient/vignette/glass/aurora/liquid), layered on top of the backdrop primitives. |
| showClose | boolean | true | Show the built-in × close button. Default: true. |
| closeButtonPosition | CloseButtonPosition | 'top-end' | Where the × close button sits (RTL-aware). Default: 'top-end'. |
| scrollable | boolean | true | Body scrolls independently; header & footer stay sticky. Default: true. |
| stickyHeader | boolean | true | Pin the header while the body scrolls (requires `scrollable`). Default: true. |
| stickyFooter | boolean | true | Pin the footer while the body scrolls (requires `scrollable`). Default: true. |
| draggable | boolean | false | Drag the dialog by its header. Disabled for fullscreen. Default: false. |
| persistent | boolean | false | Non-dismissable mode: backdrop click, Esc and the × close button no longer dismiss the modal (only programmatic close()/closeModal()). Default: false. |
| autoClose | number | false | false | Auto-close after N ms. `false` (default) disables the timer. The countdown pauses while the pointer is over the dialog (see `pauseOnHover`). |
| autoCloseProgress | boolean | true | Show a depleting countdown progress bar while `autoClose` runs. Default: true when `autoClose`. |
| pauseOnHover | boolean | true | Pause the `autoClose` countdown while the pointer is over the dialog. Default: true. |
| lockScroll | boolean | true | Lock `<body>` scroll while the modal is open. Combine with `scrollbarPadding` to avoid layout shift. Default: true. |
| disableScroll | boolean | none | Alias of `lockScroll` (Micromodal naming). When set, overrides `lockScroll`. |
| scrollbarPadding | boolean | true | Compensate for the scrollbar width on `<body>` while locking scroll, so the page does not shift when the scrollbar disappears. Default: true. |
| url | string | none | Fetch remote HTML into the body. Shows the loading state until resolved. |
| iframe | string | none | Render an `<iframe src>` body sized to the dialog. |
| image | string | none | Image URL shown in the body (pairs with `lightbox` styling). |
| imageAlt | string | '' | Alt text for the `image` body. Default: ''. |
| lightbox | boolean | false | Borderless image lightbox styling (transparent dialog chrome). Default: false. |
| loading | boolean | false | Show the loading state immediately (spinner replaces the body). Default: false. |
| loaderHtml | string | none | Custom spinner content (HTML string). Defaults to the built-in spinner. |
| autofocus | boolean | true | Auto-focus the first focusable element (or `[autofocus]`) on open. Default: true. |
| initialFocus | HandlerTarget | false | none | Explicit element to focus on open. `false` focuses the dialog container. |
| disableFocus | boolean | false | Skip auto-focus entirely (Micromodal parity). Default: false. |
| returnFocus | boolean | true | Restore focus to the previously focused element on close. Default: true. |
| theme | GSModalTheme | 'auto' | Visual theme. `auto` follows prefers-color-scheme. Default: 'auto'. |
| accentColor | string | none | Accent color for the focus ring / close button (CSS var --gsm-accent). |
| rtl | boolean | false | Right-to-left layout. Default: false. |
| customClass | GSModalCustomClass | none | Per-part class overrides. |
| className | string | none | Extra class name applied to the overlay root. |
| trigger | HandlerTarget | none | Element(s) that open the modal on click. selector | HTMLElement | React ref. |
| closeHandler | HandlerTarget | none | Element(s) inside the content that close the modal on click. selector | HTMLElement | React ref. |
| icon | GSModalIcon | false | Built-in animated icon shown above the body. One of success/error/warning/info/question, or `false` (default) for none. |
| iconColor | string | none | Override the preset icon color (defaults to a per-icon semantic color). |
| text | string | none | Plain-text body (escaped). Rendered as the modal body for presets. |
| html | string | none | Rich HTML body content (string). Rendered as the modal body for presets. |
| showConfirm | boolean | false | Show the confirm button. Default: true for presets. |
| showCancel | boolean | false | Show the cancel button. Default: false. |
| confirmText | string | none | Confirm button label. Default: 'OK'. |
| cancelText | string | none | Cancel button label. Default: 'Cancel'. |
| confirmColor | string | none | Confirm button background color. |
| cancelColor | string | none | Cancel button background color. |
| reverseButtons | boolean | false | Invert the confirm/cancel button order. Default: false. |
| role | GSModalRole | 'dialog' | ARIA role for the dialog. `alertdialog` (used for presets/confirmations) defaults `closeOnEsc` and `closeOnBackdrop` to false. |
Cycles keyboard focus inside the dialog while open.
Freezes the background without layout shift.
Opens dialogs on top of dialogs with correct z-order.
Dim, blur, glass and gradient backdrop layers.