Modal

A centered overlay dialog with header / title / body / footer slots, six content sizes, six theme colours, and a modelValue binding contract that matches drawer / popover / toast. Renders into a body portal to escape transformed ancestors and stays fully invisible while closed (no shadow halo bleed). Toggle Vue / CSS to switch the live demo and source together.

Basic

Simple modal with title, body, and close button.

Vue SFC

Header & footer slots

The modal projects four regions:

Slot	Alias	Renders
header	head	Replaces the whole default header (title + ✕)
title	—	Just the heading, keeping the default ✕
body	(default slot)	Main content — unslotted children land here
footer	foot	Action row under the body

header and footer are the preferred names and match mono-drawer. The original head and foot still work, so existing markup keeps rendering. If you supply both spellings for the same region, the alias wins (header beats head) and the other is ignored.

Vue SFC

Sizes

size sets the content scale — header/title type, body type, padding, the close button and the corner radius — across xs, sm, md (default), lg, xl and xxl. It does not change the panel width: every panel in the demo below is the same width. Use width for that, so a compact sm dialog can still be wide.

Changed

size used to be a width preset (sm 380px … xl 880px) and did nothing to the type scale. Panels that relied on size for their measure should now pass width instead.

Vue SFC

Width & height

For full control, set width, height, min-width, max-width, min-height or max-height directly. Each accepts a CSS string ("760px", "12rem", "80%") or a number — numbers are treated as px (so :width="480" → 480px). Both kebab-case (min-width) and camelCase (minWidth) work. Set both width and height to "100%" for true full screen.

Vue SFC

Auto full-screen

Set auto-fullscreen and the modal fills the screen on small viewports. It defaults to sm (under 640px); pass md, lg, xl or 2xl to move the boundary. Any authored width / height is overridden while it applies and restored above it.

Scroll lock

While open, a modal locks page scroll — lock-scroll, default true. Opt out with :lock-scroll="false" when the page behind should stay scrollable.

<mono-modal v-model="open" :lock-scroll="false" />

The lock is shared, not per-instance: overlapping overlays (a modal opened from a drawer, stacked modals, a sidebar) all draw on one lock, so scroll is released only when the last one that wanted it closes. mono-sidebar takes the same prop.

Stacked

Set stackable to let modals stack — open a modal from inside another, any depth. Each new modal sits above the previous, only one backdrop dims the screen, and Esc / overlay-click affect only the topmost. Without stackable a modal is exclusive: opening one closes any other open modal.

Vue SFC

Z-index

By default the modal takes its stacking level from mono's shared popup stack, so the newest layer is always on top. Set z-index to pin it instead — for sitting above (or below) something the host app already positions, like a sticky header or a third-party widget. The value is the overlay's level; the panel renders one above it. Accepts z-index="1500", :z-index="1500" and :zIndex="1500".

Vue SFC

Draggable

Set draggable to let users move the modal by its header — handy with stacked modals to slide the top one aside and see what's behind. The panel follows the pointer freely while dragging, but snaps back fully inside the viewport when you drop it.

Vue SFC

Colors

All built-in color variants.

Vue SFC

Confirmation

Cancel + Confirm footer that triggers a status update.

Vue SFC

Form

Modal containing an input + submit button.

Vue SFC

Persistent

Overlay-click and Escape do not close — only the buttons or the ✕ work.

Vue SFC

No overlay

Page behind stays interactive.

Vue SFC

Event log

The modal emits mno-click on every state change, plus mno-open (on open) and mno-close (on close) — matching the drawer. Each event's detail.source (overlay / close / escape / manual) says what triggered it. The log below shows the close events and their source.

Vue SFC

Customized

Override per-element styling with cssClass (Vue) or utility classes (CSS).

Vue SFC

CSS Variables

Vue SFC

Every modal is themed through --mono-modal-* custom properties. Because the dialog renders through a <body> portal, --mono-modal-* set inline on the <mono-modal> element are forwarded to the portal (so per-instance theming works); you can also set them on :root to theme every modal, and they pierce the shadow-DOM boundary for the shadow build. The size and color props set presets, but an explicit --mono-modal-* override always wins. To re-skin globally, set the underlying --theme-* tokens.

Variable	Default	Controls
--mono-modal-accent	--theme-primary	Header tint, title, close-hover, scrollbar (set by color)
--mono-modal-bg	--theme-surface	Panel background
--mono-modal-text	--theme-text	Panel text color
--mono-modal-border	--theme-border	Panel + head/foot border
--mono-modal-head-bg	accent 10%	Header gradient base
--mono-modal-radius	18px	Panel corner radius (set by size)
--mono-modal-pad-x	1.4rem	Head / body / foot horizontal padding (set by size)
--mono-modal-head-pad-y	1.1rem	Header vertical padding (set by size)
--mono-modal-foot-pad-y	0.9rem	Footer vertical padding (set by size)
--mono-modal-title-font	--theme-title-font-lg	Title font size (set by size)
--mono-modal-body-font	--theme-subtitle-font-lg	Body font size (set by size)
--mono-modal-close-size	28px	Close-button box (set by size)
--mono-modal-width	min(90vw,520px)	Panel width — not set by size; use the width prop
--mono-modal-overlay-bg	rgba(15,48,96,.45)	Backdrop scrim color
--mono-modal-shadow	accent glow	Panel shadow
--mono-modal-z	600	Base z-index (the popup stack overwrites this per level; prefer the z-index prop, and note an inline var still wins over it)

Types

Importimport { ModalProps } from 'mono-helper'

Prop	Value	Default	Description
modelValue	boolean	—	Open state, two-way bound for v-model-style usage.
size	'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl'	—	Width preset of the modal panel.
color	'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info'	—	Theme color applied to accents.
title	string	—	Heading text shown in the modal header.
dismissible	boolean	—	Shows the close button and allows dismissal.
persistent	boolean	—	Prevents closing via overlay click or escape.
overlay	boolean	—	Renders a backdrop overlay behind the panel.
closeOnEscape	boolean	—	Closes the modal when the Escape key is pressed.
closeOnOverlay	boolean	—	Closes the modal when the overlay is clicked.
lockScroll	boolean	—	Locks body scroll while the modal is open.
draggable	boolean	—	Allow dragging the modal by its header; it snaps back inside the viewport on drop.
autoFullscreen	'sm' | 'md' | 'lg' | 'xl' | '2xl' | boolean	—	Fill the screen at a breakpoint and below (default `false`). `auto-fullscreen` on its own means Tailwind's `sm` (< 640px); a token moves the boundary, so `auto-fullscreen="lg"` covers everything `lg:` does not match (< 1024px).
stackable	boolean	—	Allow this modal to stack on top of others. When false (default) it is exclusive — opening it closes any other open modals.
width	string | number	—	Explicit panel sizing. Each accepts a CSS length string (`"12px"`, `"12rem"`, `"80%"`) or a number / numeric string (interpreted as px). Set both `width` and `height` to `"100%"` for true full-screen.
height	string | number	—	—
minWidth	string | number	—	—
maxWidth	string | number	—	—
minHeight	string | number	—	—
maxHeight	string | number	—	—
zIndex	string | number	—	Pin the modal to an explicit stacking level. Unset (the default) lets the shared popup stack assign one so the newest layer is always on top. The value is the overlay's `z-index`; the panel sits one above it.
cssClass	ModalCssClass	—	Per-part class overrides for internal elements.
cssClassName	string	—	Plain root class string applied to the modal.