Modals

A blocking panel centred over the page: a small base — trigger, overlay, modal, dialog, header, actions — and 51 compositions pairing 1:1 with the sheet.

Specimen

Guidelines

Code

Demo

The panel at rest, and the trigger that opens it. Pick the configurable base or any of the 51 Types; every one is drawn here and opens for real.

Blog post published

This blog post has been published. Team members will be able to edit this post and republish changes.

Type

Header align

Actions layout

Close button

Padding bottom

Divider

Featured icon

Destructive

isDismissable

import { CheckCircle } from "@untitledui/icons"; import { Heading } from "react-aria-components"; import { Dialog, DialogTrigger, Modal, ModalActions, ModalHeader, ModalOverlay, } from "@/components/application/modals/modal"; import { Button } from "@/components/base/buttons/button"; import { FeaturedIcon } from "@/components/foundations/featured-icon/featured-icon"; <DialogTrigger> <Button color="secondary">Open the modal</Button> <ModalOverlay isDismissable> <Modal className="sm:max-w-100"> <Dialog> {({ close }) => ( <> <ModalHeader onClose={close} paddingBottom > <div className="relative w-max"> <FeaturedIcon color="success" size="md" theme="modern" icon={CheckCircle} /> </div> <div className="flex flex-col gap-0.5"> <Heading slot="title" level={2} className="text-md text-primary font-semibold"> Blog post published </Heading> <p className="text-tertiary text-sm">This blog post has been published. Team members will be able to edit this post and republish changes.</p> </div> </ModalHeader> <ModalActions> <Button color="secondary" size="md" onClick={close}> Cancel </Button> <Button color="primary" size="md" onClick={close}> Confirm </Button> </ModalActions> </> )} </Dialog> </Modal> </ModalOverlay> </DialogTrigger>

A four-part base, two new components, and 51 compositions on top

ModalOverlay is the backdrop and the centring, Modal is the panel, Dialog is the content box inside it, and DialogTrigger owns the open state. Until the 2026-08-24 edit that was the entire family API, and all 51 compositions hand-rolled their own header and action row — ModalHeader and ModalActions are new, built to the sheet’s own axes. Everything a Type looks like beyond those two — the icon, the fields, the images, the buttons — is still children you write.

The Type control is the catalogue, not a prop: the family has no type, so picking one swaps the whole composition rather than setting an axis. Choose Base and the panel becomes configurable again, with every switch the base actually owns. The copied snippet follows: a Type gives you the import for its file, because a Type is a file.

Contextual demo

A modal only makes sense over the screen it interrupts: real dialogs over a real page, with no docs shell in the way.

View in a page

The family

Four React Aria primitives with the kit’s classes on top, plus the ModalHeader and ModalActions added 2026-08-24.

The components in this family, with their descriptions and import paths
Component	Description	Import from
DialogTrigger	React Aria’s DialogTrigger, re-exported unchanged. Give it two children — the button and the ModalOverlay — and it owns the open state, the trigger’s aria-expanded and aria-haspopup, and focus return.	`@/components/application/modals/modal`
ModalOverlay	The fixed backdrop: bg-overlay/70 with an 8px blur, and the px/py that decide how much vertical room the panel has. Its --modal-pt and --modal-pb are what the panel’s max-height subtracts.	`@/components/application/modals/modal`
Modal	The panel: bg-primary, a 16px radius at both breakpoints, shadow-xl, a forced-colors border, and a max-height computed from the overlay’s padding. The per-Type width goes here as a className.	`@/components/application/modals/modal`
Dialog	The dialog inside the panel: max-h-[inherit] and overflow-y-auto. Children can be a function receiving close, which is how a header’s onClose and a footer’s Cancel dismiss without any state of yours.	`@/components/application/modals/modal`
ModalHeader	New on 2026-08-24. The sheet’s _Modal header as a component: three align modes, the absolutely positioned close button, and the optional 20px spacer and 1px rule. Adopted in one composition so far.	`@/components/application/modals/modal`
ModalActions	New on 2026-08-24. The sheet’s _Modal actions as a component: fill, stacked or end, all three stacking below sm with flex-col-reverse so the primary sits on top there while staying last in the DOM.	`@/components/application/modals/modal`

Built from

The pieces with their own docs page.

Component	Where it’s used here
CloseButton	The header’s close affordance, at size sm (36 with a 20px icon) everywhere except user settings, which the sheet draws at size lg (44 with a 24px icon). It fills React Aria’s close slot, so it dismisses the dialog with or without an onClose.
FeaturedIcon	The header glyph on 29 of the 51 compositions, at size md theme modern: a 40px box with an 8px radius and a 20px icon.
Button	The action row, at size md — px-3.5 py-2.5 with an 8px radius. A destructive confirm is the same button with color="primary-destructive".
Checkbox	The “don’t show again” affordance leading the end-aligned action row, and the body of the checkboxes and team-invite Types.
Select	The pickers and comboboxes inside the panels — roles, templates, labels, and the tag select on both New message Types.
Avatar	The people in the team, invite, share and access Types, usually through AvatarLabelGroup, and AvatarProfilePhoto on the two settings panels.

Anatomy

A panel is bg-primary, rounded-2xl and shadow-xl: header, body, action row. Two confirmed widths, from real parts.

Blog post published

This blog post has been published. Team members will be able to edit this post and republish changes.

Don’t show again

544px, the Horizontal Type: a featured icon beside the text column from sm up, and an action row aligned to the end with a checkbox at its start

Blog post published

This blog post has been published. Team members will be able to edit this post.

Share on X

Share on Medium

Share on Facebook

400px, the stacked left-aligned Type: the icon above the text, a 20px padding-bottom spacer, content, and two buttons sharing the width

Ceiling	Class on Modal	Against the sheet	Where the family draws it
400px	`sm:max-w-100`	Read 2026-08-24	The family’s default, on 22 files — 21 of them on Modal, plus Centered photo carousel on an inner element. Every short confirmation, the sign-in and sign-up pair, and the three team Types
408px	`sm:max-w-102`	Counted in the kit	Verification code, alone
440px	`sm:max-w-110`	Counted in the kit	Integration, alone
480px	`sm:max-w-120`	Read 2026-08-24	10 files: the three payment Types, Plan 01, New project, Share project, Profile settings, File upload, User selection and the A.I. assistant
512px	`sm:max-w-128`	Read 2026-09-01	2FA code, alone
544px	`sm:max-w-136`	Read 2026-08-24	The three horizontal Types — Horizontal, Warning horizontal and Destructive horizontal
548px	`sm:max-w-137`	Counted in the kit	Banner appearance, alone — and the one value off the theme’s own scale
560px	`sm:max-w-140`	Counted in the kit	Image crop and Plan 02
608px	`sm:max-w-152`	Counted in the kit	Centered video carousel, set on an inner element rather than on Modal
640px	`sm:max-w-160`	Read 2026-08-24	4 files: Form 01, both New message Types, and User settings
688px	`sm:max-w-172`	Read 2026-09-01	Appearance settings and Form 02
720px	`sm:max-w-180`	Counted in the kit	Text editor, set on an inner element rather than on Modal
800px	`sm:max-w-200`	Read 2026-09-01	Create event, the widest panel in the family
—	`none`	Counted in the kit	Date picker sets no width at all and takes it from the calendar inside

Those numbers are ceilings, not widths

Modal sets a max-width and no width, and it is a flex item in the overlay, so the panel is content-sized up to its ceiling rather than filling it. Measured against a production build: the Horizontal confirm reaches 544 of 544 and the Centered photo 400 of 400, but the form modal reaches only 486 of its 640 ceiling — it fills only when its content is wide enough to. The two cells above therefore set their widths outright, because a specimen documenting a 544px panel has to be 544px. The sheet draws the panel w-full max-w-[400px], so it always fills; that difference is recorded for a ruling rather than changed here, since changing it would resize every modal in the family.

Why these are boxes and not overlays

Both cells compose the real ModalHeader and ModalActions — the same elements a composition uses, with the same paddings — inside a bounded relative box carrying the panel’s own bg-primary, rounded-2xl and shadow-xl. What they do not mount is ModalOverlay, because it renders fixed inset-0: two of them side by side is one dialog on top of another, over the whole page. The live section below shows the overlay doing its real job, one at a time, behind a trigger.

They also all pass showCloseButton=. Outside a real Dialog, CloseButton’s slot="close" resolves to nothing, so the button would be a focusable control announcing “Close” that closes nothing — six of them in the page’s tab order. The live section renders it doing its job instead.

The radius stopped stepping, and the panel grew an edge

The kit drew rounded-xl sm:rounded-2xl — 12 at a phone width, 16 above it. The sheet draws radius-2xl, 16, at both breakpoints (4057:415360 Desktop, 4057:421981 Mobile), so the 2026-08-24 edit dropped the step. The same edit gave the panel a forced-colors border, which the specimens above carry too: the panel’s only separation from the page was shadow-xl over a bg-overlay/70 backdrop, and forced colors drops the shadow and flattens the backdrop, leaving no edge at all. It had to be a border rather than the outline the slideout family uses, because outline-hidden sits on all three of ModalOverlay, Modal and Dialog here, and Tailwind v4 emits that as outline: 2px solid transparent under forced colors specifically — an outline on the same element would set a width against a transparent colour and paint nothing.

The widths are honest; the paddings inside them are the window’s

The 400px cell is the panel at that width, not a 400px viewport. Every switch this family has — the header’s px-4 pt-5 sm:px-6 sm:pt-6, the action row’s p-4 pt-6 sm:px-6 sm:pt-8 sm:pb-6, the alignment’s sm:flex-row, the layout’s sm:grid — is a media query on the viewport, so at a desktop window these cells draw the desktop treatment at a narrow width. Narrow the browser, or open the contextual demo, to see each pair resolve. One thing genuinely does not change across the breakpoint: the title is text-md 16/24 semibold at both, over text-sm/20 tertiary support. Slideouts step 18 to 16; modals do not.

The header

The sheet’s _Modal header as a component: three alignments, four booleans, and the close button rendered first.

Blog post published

Team members will be able to edit this post.

align="left", the default: the icon sits above the text column, the whole block flex-col at gap-4

Delete blog post

Are you sure you want to delete this post?

align="horizontal": flex-col sm:flex-row, so the icon moves beside the text from 640px up and stacks below it

Share this project

Anyone with the link can view this project.

align="center": items-center plus text-center, the Centered photo and Centered video shape

Invite your team

Add colleagues by email address.

Content begins here, under the rule.

paddingBottom and divider: a 20px spacer and a 1px rule under the block, the sheet’s two separation booleans

Create a new project

Upload an image to create a new project.

No featured icon: the sheet’s featuredIcon boolean, expressed by rendering less. The X on every in-flow specimen is drawn, not wired — see the note below.

The close button, and its one exception

The X is CloseButton size="sm" — 36px box, 8px radius, 20px icon — at top-3 right-3 sm:top-4 sm:right-4, and it matched the sheet on all five values in seven of the eight Types read. In flow, on this page, it is drawn in that geometry but not wired: outside a real Dialog the slot="close" resolves to nothing, and a focusable “Close” that closes nothing is a defect. The Demo above renders the real button. The exception is User settings, which the sheet draws at 44 with a 24px icon over its cover photo; the 2026-08-24 edit sets that file to size="lg", which is exactly 44 and 24. It is a hand-rolled button in that composition rather than a ModalHeader prop, because that Type has no header block for it to sit in.

What the component does not decide

Nothing inside the header is a prop. The featured icon is size="md" theme="modern" — a 40px box, 8px radius, 20px icon — and its colour is the Type’s business: success on a publish, error on a delete, gray on a form. The title is your Heading slot="title" and the support text your <p>, at gap-0.5. Passing that as children rather than as props is what lets a Type swap its support copy per breakpoint, which several do.

The action row

The sheet’s _Modal actions: three layouts and two leading slots. Every kit layout stacks below 640px; the sheet has a mode that does not.

layout="fill", the default: sm:grid sm:grid-cols-2, so the two buttons share the width evenly from 640px up

layout="stacked": no sm: layout class at all, so full-width buttons at every width — and the reversal below still puts Confirm on top

Don’t show again

layout="end": sm:flex-row sm:items-center sm:justify-end. The sheet’s "Horizontal right aligned (checkbox)" Type fills both of its optional leading slots by default — a checkbox and a tertiary button — and pushes the pair to the end edge

Don’t show again

Destructive is a recolour and nothing else: primary-destructive on the confirm button, with every padding, gap, radius, order and leading slot identical

The stacked row with its sm: classes removed, so it draws its phone-width form at any window: Cancel is first in the DOM and second on the screen

flex-col-reverse is the whole trick

The sheet’s Mobile modes put Confirm above Cancel; every other breakpoint puts Cancel first, reading order left to right. Reordering the DOM per breakpoint would be a mess, and reordering it once would put the destructive or committing button first in the tab order on every screen. Instead the row is flex-col-reverse at its base and picks up a layout class from sm up — so the primary is on top at a phone width while staying last in the DOM, last in the tab order, and last for a screen reader. All 34 compositions carrying this row do it the same way, and it is the one thing in the family that was already uniform.

Nine spellings of three layouts, which is why the component exists

Across the family the same row was written nine different ways — 19 files at *:grow sm:grid sm:grid-cols-2, three without the *:grow, five at sm:flex-row sm:items-center, and five more one-off variations, two of which contradict themselves (a sm:grid that also sets sm:flex-row, and another that sets justify-end on a grid, where it is inert). ModalActions names the three shapes those nine were reaching for. It does not yet normalise them: the one adopting file still passes its *:grow along as a className so the render is byte-identical. Dropping those extras was waiting on a measurement, and that measurement has since run: the row computes flex-grow: 1 under a parent that computes display: block, and computes display: grid itself, so both *:grow and the row’s flex flex-1 are inert. The 34-file sweep is now known-safe rather than an inference.

Three booleans on this set, and what became of each

Read from 4057:414373 on 2026-08-31, the set carries checkbox, tertiaryButton and divider, all three true by default. The first two are children in the kit, the same way the header’s featuredIcon is: you write a Checkbox and a tertiary Button into ModalActions and push them with sm:mr-auto, which is what the two endcells above do. The third is not implemented at all — its 25px “Divider-wrap” spacing is unverified and no kit file exercises it, so it is recorded as Figma-only rather than guessed at. ModalHeader’s divider, which is implemented above, is a plain 1px rule with no wrapper.

A third breakpoint mode the kit cannot express

The header set is drawn at two breakpoints; this one is drawn at three. Desktop and Mobile vertical aligned are what ModalActions reproduces — a row above 640px, a reversed column below it. The third, Mobile horizontal aligned (12007:566703 and its two siblings, read 2026-08-31), keeps the buttons in a row at a phone width: Cancel first, both flex-[1_0_0], inside a Content column that carries the checkbox and tertiary button beneath them rather than beside them. The kit has one sm:prefix and no third mode, so every layout stacks below 640px unconditionally. That is a kit limit rather than the sheet’s design, and it is worth knowing before reading “all three stack below sm” as parity.

The overlay

The backdrop, the padding and the centring: a fixed inset-0 flex box, bottom-sheet below 640px and centred above it.

The page behind the modal

Body copy, a rule, and a block of colour — enough texture that the blur has something to work on.

bg-overlay/70 with backdrop-blur-[8px], over content. Open any live modal above to see the same treatment over this whole page

The height contract, live. Twelve rows under a 480px ceiling: shorten the browser window and the panel stops growing at the viewport height, and the whole dialog scrolls — header and action row included

Why this one is still behind a trigger

Every other Type on this page is drawn in flow and opened from the Demo. The height contract cannot be drawn: it is the panel stopping at the viewport and the whole dialog — header and action row included — scrolling inside it, which only a real overlay at a real window height can show. Shorten the browser and open it.

The padding is a pair of custom properties, and one of them is responsive

Horizontal padding is px-4 sm:px-8, matching the sheet’s 16 and 32 directly. Vertical padding runs through --modal-pt and --modal-pb so the panel’s max height can subtract it: 16 top and 32 top, against a bottom of clamp(16px, 8vh, 64px) at a phone width and a flat 32 above it. The sheet draws a fixed 64 at the bottom on Mobile, and at the 812px viewport it is drawn on, 8vh is 65 and clamps to exactly that — so the two agree everywhere the sheet can be checked, and the kit keeps shrinking below roughly 800px tall, which a static frame cannot express.

An arbitrary value, by ruling

The sheet’s backdrop-blur is a Figma radius of 16, which halves to 8px in CSS by the rule theme.css records. The kit drew 6. The theme’s blur scale has no 8 — sm 2, md 4, lg 6, xl 10 — and Figma’s backdrop-blur scale and the theme’s blur scale do not share a naming, so the 2026-08-24 edit writes backdrop-blur-[8px] rather than tokenising it. That is the same 8px the slideout family took in the previous batch, so the two backdrops now agree. Whether it earns a token is a proposal, not a read result. The fill is bg-overlay, which is interface-950 in light and switches to interface-800 in dark; the sheet is drawn in light only, so the dark value is unread.

The catalogue

The same 51 as an index: which file each Type is, and its width. What each one contains is drawn above.

Type	File	Width
Access request	`access-request-modal.tsx`	`sm:max-w-100`
A.I. assistant	`ai-assistant-modal.tsx`	`sm:max-w-120`
Appearance settings	`appearance-settings-modal.tsx`	`sm:max-w-172`
Banner appearance	`banner-appearance-modal.tsx`	`sm:max-w-137`
Calendar event	`calendar-event-modal.tsx`	`sm:max-w-100`
Centered photo carousel	`centered-photo-carousel-modal.tsx`	`sm:max-w-100`
Centered photo	`centered-photo-modal.tsx`	`sm:max-w-100`
Centered video carousel	`centered-video-carousel-modal.tsx`	`sm:max-w-152`
Checkboxes	`checkboxes-modal.tsx`	`sm:max-w-100`
Create event	`create-event-modal.tsx`	`sm:max-w-200`
Date picker	`date-picker-modal.tsx`	none — sized by its calendar
Destructive horizontal	`destructive-horizontal-modal.tsx`	`sm:max-w-136`
Destructive stacked left aligned	`destructive-stacked-left-aligned-modal.tsx`	`sm:max-w-100`
Dropdown	`dropdown-modal.tsx`	`sm:max-w-100`
Email invite	`email-invite-modal.tsx`	`sm:max-w-100`
File upload	`file-upload-modal.tsx`	`sm:max-w-120`
Form 01	`form-01-modal.tsx`	`sm:max-w-160`
Form 02	`form-02-modal.tsx`	`sm:max-w-172`
Horizontal	`horizontal-modal.tsx`	`sm:max-w-136`
Image crop	`image-crop-modal.tsx`	`sm:max-w-140`
Input field	`input-field-modal.tsx`	`sm:max-w-100`
Integration	`integration-modal.tsx`	`sm:max-w-110`
Labels	`labels-modal.tsx`	`sm:max-w-100`
Link field	`link-field-modal.tsx`	`sm:max-w-100`
Log in	`login-modal.tsx`	`sm:max-w-100`
New message (empty state)	`new-message-empty-state-modal.tsx`	`sm:max-w-160`
New message (filled)	`new-message-filled-modal.tsx`	`sm:max-w-160`
New project	`new-project-modal.tsx`	`sm:max-w-120`
Password prompt	`password-prompt-modal.tsx`	`sm:max-w-100`
Payment details	`payment-details-modal.tsx`	`sm:max-w-120`
Payment details with image	`payment-details-with-image-modal.tsx`	`sm:max-w-120`
Payment method	`payment-method-modal.tsx`	`sm:max-w-120`
Plan 01	`plan-01-modal.tsx`	`sm:max-w-120`
Plan 02	`plan-02-modal.tsx`	`sm:max-w-140`
Profile settings	`profile-settings-modal.tsx`	`sm:max-w-120`
Share project	`share-project-modal.tsx`	`sm:max-w-120`
Sign up 01	`signup-01-modal.tsx`	`sm:max-w-100`
Sign up 02	`signup-02-modal.tsx`	`sm:max-w-100`
Stacked left aligned	`stacked-left-aligned-modal.tsx`	`sm:max-w-100`
Stacked with team and invites	`stacked-with-team-and-invites-modal.tsx`	`sm:max-w-100`
Stacked with team and link	`stacked-with-team-and-link-modal.tsx`	`sm:max-w-100`
Stacked with team	`stacked-with-team-modal.tsx`	`sm:max-w-100`
Text editor	`text-editor-modal.tsx`	`sm:max-w-180`
Toggles	`toggles-modal.tsx`	`sm:max-w-100`
2FA code	`twofa-code-modal.tsx`	`sm:max-w-128`
User invite	`user-invite-modal.tsx`	`sm:max-w-100`
User selection	`user-selection-modal.tsx`	`sm:max-w-120`
User settings	`user-settings-modal.tsx`	`sm:max-w-160`
Verification code	`verification-code-modal.tsx`	`sm:max-w-102`
Warning horizontal	`warning-horizontal-modal.tsx`	`sm:max-w-136`
Warning stacked left aligned	`warning-stacked-left-aligned-modal.tsx`	`sm:max-w-100`

Fifty-one Types, fifty-one files

The mapping is 1:1 and settled: no unmapped composition, no Figma-only Type, and no file without one. Until 2026-08-26 there was an extra — rtl-demo.tsx, an upstream demonstration with an I18nProvider, Arabic copy and a direction toggle. It was removed when right-to-left was ruled a non-goal: the family carries 116 physical direction classes against six logical ones, so the demo showed a capability none of the compositions around it honour. A design system should not ship a demonstration of support it does not have.

All 51 named and drawn, 11 read at the code level

The set was enumerated in full on 2026-09-01 — get_metadata on 4057:415205 returns all 102 symbols, and the 51 Type names pair 1:1 with the 51 files, checked name for name rather than asserted. On the same date all 51 Desktop symbols were rendered and reviewed against their compositions, which is what the Every Type section is built from: each panel’s width, header alignment, featured icon and glyph, action layout and button labels come from the file and were checked against the symbol.

Two things that review does not license. Eleven Types have been read at the code level — eight on 2026-08-24 under a hard eight-call budget, plus Create event, Appearance settings and 2FA code measured on 2026-09-01 — so exact paddings and token values inside the other 40 bodies are unverified, which is why the Types whose interior is another family draw a labelled stand-in rather than a guess. And every Mobiletwin beyond the base pair is still unread: this page states nothing about how a Type rearranges below 640px beyond what the base’s own breakpoint does.

Modals

Modals

Demo

Contextual demo

The family

Built from

Anatomy

The header

The action row

The overlay

Every Type

Confirmations

Team

Media

Codes and sign-in

Money, plans and files

People and sharing

Forms, editors and settings

The catalogue