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 a composable overlay component with panel, header, body, and footer slots.
| Property | Type | Default | Code mapping | Options or notes |
|---|---|---|---|---|
| Open | boolean | false | Conditional rendering of ModalOverlay | No additional constraint |
| Size | variant | lg | ModalPanel.size | sm, md, lg, xl |
| Backdrop closes | boolean | true | ModalOverlay.closeOnBackdrop | No additional constraint |
| Scrollable body | boolean | true | ModalBody.scroll | No additional constraint |
| HeadingRequired | text | Settings | ModalHeader.heading | No additional constraint |
| Description | text | None | ModalHeader.description | 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.
No internal breakpoint
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
384 / 512 / 672 / 896px
sm / md / lg / xl; shared with Dialog.
Panel max height
viewport − 48px mobile / viewport − 64px md+
Overlay padding
16px mobile / 24px md+
Top offset mobile
64px
Header padding
20px horizontal mobile / 24px md; 12px vertical
Body/footer padding
20px horizontal mobile / 24px md; 16px 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.