Overlay
RequiredMounted dialog root, scroll container, backdrop, and focus scope.
Overlays
A composable Headless UI modal shell for richer application layouts with header, body, and footer regions.
ModalOverlayModalPanelModalHeaderModalBodyModalFooterModalSizeConfigure the production component, inspect it at responsive widths, copy synchronized JSX, and share the exact state from one workspace.
This JSX stays synchronized with the controls and uses only public package APIs.
'use client';
import { useState } from 'react';
import { Button, ModalBody, ModalFooter, ModalHeader, ModalOverlay, ModalPanel } from '@ai-created/ui';
export function Example() {
const [open, setOpen] = useState(false);
if (!open) {
return <Button onClick={() => setOpen(true)}>Open modal</Button>;
}
return (
<ModalOverlay onClose={() => setOpen(false)}>
<ModalPanel>
<ModalHeader heading="Edit project" onClose={() => setOpen(false)} />
<ModalBody>Modal content belongs here.</ModalBody>
<ModalFooter>
<Button onClick={() => setOpen(false)}>Save changes</Button>
</ModalFooter>
</ModalPanel>
</ModalOverlay>
);
}
import { ModalOverlay, ModalPanel, ModalHeader, ModalBody, ModalFooter } from '@ai-created/ui';Client boundary
'use client' to the file that owns this interactive state.Replace the version placeholder with the release tag your product has reviewed.
npm install --install-links "git+https://github.com/TheMarco/ai-created-ui.git#vX.Y.Z"@import '@ai-created/ui/styles/tokens.css';
@tailwind base;
@tailwind components;
@tailwind utilities;module.exports = {
presets: [require('@ai-created/ui/tailwind-preset')],
content: [
'./src/**/*.{js,ts,jsx,tsx,mdx}',
'./node_modules/@ai-created/ui/src/**/*.{js,ts,jsx,tsx}',
],
};Named regions define what belongs to the component, what remains optional, and where semantic responsibility lives.
Mounted dialog root, scroll container, backdrop, and focus scope.
Bounded flex-column Surface.
Optional eyebrow, title, description, custom content, and close action.
Primary content region with optional internal scrolling.
Optional bordered action region.
The Figma-equivalent asset model, auto-layout, resizing, properties, slots, content bounds, localization, and governance contract.
Asset kind
component
Design library name
Components/Overlays/Modal
Maturity
stable
Last reviewed
2026-08-29
Canvas applicability
Publish one assembled Modal with an exposed Header and direct native Body/Footer slots, plus the public overlay, panel, header, body and footer building blocks.
| Property | Type | Default | Code mapping | Options or notes |
|---|---|---|---|---|
| Size | variant | lg | ModalPanel.size | lg, sm, md, xl |
| Viewport | variant | wide | Region padding at md | wide, compact |
| Body layout | variant | hug | Canvas height preview: natural content or a constrained scrollable ModalBody | hug, scroll |
| Show footer | boolean | true | Presence of ModalFooter | No additional constraint |
| Heading (nested Header)Required | text | Workspace settings | ModalHeader.heading | No additional constraint |
| Description (nested Header) | text | Manage access and defaults for your team. | ModalHeader.description | No additional constraint |
| Show description (nested Header) | boolean | true | Presence of ModalHeader.description | No additional constraint |
| Close (nested Header) | variant | shown | Presence of ModalHeader.onClose | shown, hidden |
| Eyebrow (nested Header) | slot | None | ModalHeader.eyebrow | No additional constraint |
| Show eyebrow (nested Header) | boolean | false | Presence of ModalHeader.eyebrow | No additional constraint |
| Header content (nested Header) | slot | None | ModalHeader.children | No additional constraint |
| Show header content (nested Header) | boolean | false | Presence of ModalHeader.children | No additional constraint |
| BodyRequired | slot | None | ModalBody children | No additional constraint |
| Footer | slot | None | ModalFooter children | No additional constraint |
Backdrop, semantics, dismissal, and focus boundary.
ModalOverlaySized modal surface.
ModalPanelHeading, optional description, and close control.
ModalHeaderPrimary scroll region.
ModalBodyAction region.
ModalFooterOverflow: Wrap; never truncate.
The modal task should remain clear.
Overflow: Move tertiary actions into body content.
A contained decision needs a clear hierarchy.
Overflow: Use a full page for broad or deeply nested tasks.
Modal interruption cost rises with complexity.
Translatable: Heading, Description, Body, Action labels
Panel is viewport-constrained and body may scroll.
sm vertical centering / md viewport and region padding
Accountable owner
Design systems overlay primitive owner
Canonical source: src/components/Modal.tsx
These measurements and semantic tokens define the supported visual contract. Local overrides should preserve the same hierarchy and interaction cues.
Panel max width
480 / 640 / 840 / 1120px
sm / md / lg / xl; shared with Dialog.
Panel max height
viewport − 60px mobile / viewport − 80px md+
Overlay padding
20px mobile / 30px md+
Top offset mobile
80px
Header padding
20px horizontal mobile / 24px md; 12px vertical
Body/footer padding
25px horizontal mobile / 30px md; 20px vertical
Close target
44 × 44px
Close glyph
24 × 24px
Close glyph inset
16px from top and logical end
Shared with Dialog; the target does not determine header height.
--color-overlayBackdrop.
--color-surface / --color-borderPanel and dividers through Surface.
--color-text / --color-text2Heading and description.
--radius-mdPanel radius.
A component is not complete until its passive, interactive, disabled, and exceptional states remain understandable in both themes.
Semantics, accessible naming, keyboard behavior, focus and announcements are implementation requirements, not optional documentation.
Use the public package API and preserve the controlled-state, native-attribute, and ref contracts described below.
import { ModalOverlay, ModalPanel, ModalHeader, ModalBody, ModalFooter } from '@ai-created/ui';Client Component required
<ModalOverlay onClose={onClose}><ModalPanel><ModalHeader heading="Settings" onClose={onClose} /><ModalBody>...</ModalBody><ModalFooter>...</ModalFooter></ModalPanel></ModalOverlay>These props and helpers are compatibility contracts. Changes require migration guidance and release notes.
| Prop | Type | Default | Contract |
|---|---|---|---|
| ModalOverlay.onClose | () => void | undefined | Dismiss callback. |
| ModalOverlay.closeOnBackdrop | boolean | true | Whether backdrop clicks dismiss. |
| ModalPanel.size | ModalSize | lg | sm, md, lg, or xl. |
| ModalHeader.heading | ReactNode | required | Heading content. |
| ModalHeader.onClose | () => void | undefined | Optional close action. |
| ModalBody.scroll | boolean | true | Allows the body region to scroll. |
| children | ReactNode | required | Content for each region. |
These rules keep the component recognizable across products without preventing deliberate composition.
The component should be verified as rendered UI, an interaction model, an accessibility surface, and a theme-aware visual artifact.