Overlay Components
Modal
An accessible dialog component with focus trapping, scroll lock, and keyboard navigation. Built on Overlay with ARIA role="dialog" and aria-modal="true".
An accessible dialog component with focus trapping, scroll lock, and keyboard navigation. Built on Overlay with ARIA role="dialog" and aria-modal="true". Sub-components: ModalHeader, ModalBody, ModalFooter, ModalCloseButton.
When to Use
When NOT to Use
Customizing
Set app-wide Modal defaults with ThemeProvider's themeDefaults:
import { ThemeProvider, Modal } from '@vaneui/ui';
<ThemeProvider themeDefaults={{ modal: { lg: true, border: true },}}> <Modal open={open} onClose={onClose}>Content</Modal></ThemeProvider>Basic Modal
A controlled modal opened by a Button. The Modal portals to document.body, traps focus inside the dialog while open, locks body scroll, and closes on overlay click or Escape.
Modal content defaults: md, primary, outline, rounded, shadow, flex column, gap, wFull, overflowAuto, relative, noPadding (sub-components own their own padding).
const [open, setOpen] = useState(false);
<Button onClick={() => setOpen(true)}>Open Modal</Button><Modal open={open} onClose={() => setOpen(false)}> <Stack> <Text bold>Confirm Action</Text> <Text>Are you sure?</Text> <Row justifyEnd> <Button onClick={() => setOpen(false)}>Cancel</Button> <Button primary filled onClick={() => setOpen(false)}>Confirm</Button> </Row> </Stack></Modal>Compound Modal
Use ModalHeader, ModalBody, ModalFooter, and ModalCloseButton for full control over layout. When any of these are direct children, Modal renders them as-is without auto-wrapping. Each sub-component carries its own layout defaults:
import { Modal, ModalHeader, ModalBody, ModalFooter, ModalCloseButton, Button, Title, Input, Label, Stack } from "@vaneui/ui";
const [open, setOpen] = useState(false);
<Modal open={open} onClose={() => setOpen(false)}> <ModalHeader> <Title>Edit Profile</Title> <ModalCloseButton /> </ModalHeader> <ModalBody> <Stack> <Label>Name</Label> <Input placeholder="Enter your name" /> <Label>Email</Label> <Input placeholder="Enter your email" /> </Stack> </ModalBody> <ModalFooter> <Button sm onClick={() => setOpen(false)}>Cancel</Button> <Button sm primary filled onClick={() => setOpen(false)}>Save</Button> </ModalFooter></Modal>Convenience Props
Use the title, footer, and withCloseButton shorthand props to compose a structured modal without writing sub-components. When title is set, a close button is shown by default (toggle with withCloseButton). Children become the body.
import { Modal, Button, Text, Row } from "@vaneui/ui";
const [open, setOpen] = useState(false);
<Modal open={open} onClose={() => setOpen(false)} title="Quick Confirmation" footer={ <Row justifyEnd> <Button sm onClick={() => setOpen(false)}>Cancel</Button> <Button sm primary filled onClick={() => setOpen(false)}>Confirm</Button> </Row> }> <Text>Are you sure you want to proceed?</Text></Modal>Confirmation Dialog
A common pattern: a destructive action that requires explicit confirmation. Disable closeOnOverlayClick so users can't dismiss accidentally by clicking outside.
const [open, setOpen] = useState(false);
<Button danger filled onClick={() => setOpen(true)}>Delete Account</Button><Modal open={open} onClose={() => setOpen(false)} closeOnOverlayClick={false} title="Delete account?" footer={ <Row justifyEnd> <Button sm onClick={() => setOpen(false)}>Cancel</Button> <Button sm danger filled onClick={() => setOpen(false)}>Delete</Button> </Row> }> <Text>This action is permanent and cannot be undone.</Text></Modal>Form Modal
Modals can host forms. Focus trapping keeps Tab / Shift+Tab navigation inside the modal, and pressing Escape closes it (unless disabled). Use initialFocus to direct keyboard focus to a specific field on open.
const [open, setOpen] = useState(false);const nameRef = useRef<HTMLInputElement>(null);
<Button onClick={() => setOpen(true)}>Edit Profile</Button><Modal open={open} onClose={() => setOpen(false)} initialFocus={nameRef} title="Edit Profile" footer={ <Row justifyEnd> <Button sm onClick={() => setOpen(false)}>Cancel</Button> <Button sm primary filled onClick={() => setOpen(false)}>Save</Button> </Row> }> <Stack> <Label>Name</Label> <Input ref={nameRef} placeholder="Enter your name" /> <Label>Email</Label> <Input type="email" placeholder="you@example.com" /> <Checkbox>Send me email updates</Checkbox> </Stack></Modal>Modal Sizes
Size props control modal content width (via the --fs-unit / --py-unit / --br-unit chain) — font-size, padding, gap, and border-radius all scale together.
<Modal open={open} onClose={onClose} sm>Small modal</Modal><Modal open={open} onClose={onClose} lg>Large modal</Modal>Modal Appearances
Apply appearance and variant props to style the content surface (border, text, background).
<Modal open={open} onClose={onClose} primary filled>Primary modal</Modal><Modal open={open} onClose={onClose} danger filled>Danger modal</Modal>Blur Overlay
Pass overlayProps={{ blur: true }} to add a backdrop-filter blur behind the modal.
<Modal open={open} onClose={onClose} overlayProps={{ blur: true }}> <Text>Blurred background</Text></Modal>Non-dismissible Modal
Disable closeOnOverlayClick and closeOnEscape to force the user to take an explicit action (typically a button in the footer) before the modal can close.
<Modal open={open} onClose={onClose} closeOnOverlayClick={false} closeOnEscape={false}> <Text>Must click a button to close</Text></Modal>Full Screen Modal
Set fullScreen to make the modal fill the entire viewport. Full-screen modals have no border-radius (sharp is applied automatically) and use a transparent overlay — useful for immersive experiences or mobile-optimized views.
<Modal open={open} onClose={() => setOpen(false)} fullScreen> <ModalHeader> <Title>Full Screen View</Title> <ModalCloseButton /> </ModalHeader> <ModalBody> <Text>Content fills the entire viewport.</Text> </ModalBody></Modal>Accessibility & Advanced Props
Modal ships accessibility features enabled by default. The dialog renders with role="dialog" and aria-modal="true", and is automatically wired with aria-labelledby (when ModalHeader is used) and aria-describedby (when ModalBody is used).
| Prop | Default | Description |
|---|---|---|
scrollLock | true | Lock body scroll when modal is open |
focusTrap | true | Trap Tab / Shift+Tab focus inside the modal |
returnFocus | true | Return focus to the trigger element on close |
initialFocus | — | Ref to the element that should receive focus on open |
portal | true | Render via portal into document.body |
keepMounted | false | Keep DOM node mounted when closed |
noAnimation | false | Disable enter/exit transitions |
transitionDuration | 200 | Animation duration in ms |
{/* Custom focus target */}<Modal open={open} onClose={onClose} initialFocus={inputRef}> <Input ref={inputRef} placeholder="Auto-focused" /></Modal>
{/* Keep mounted for animation or state preservation */}<Modal open={open} onClose={onClose} keepMounted transitionDuration={300}> <Text>Stays in DOM when closed</Text></Modal>Modal Props
| Prop | Category | Default | Description |
|---|---|---|---|
accent | Appearance | Accent color appearance (rose) | |
brand | Appearance | Brand color appearance (blue) | |
danger | Appearance | Danger color appearance (red) | |
info | Appearance | Info color appearance (cyan) | |
inherit | Appearance | Inherit appearance from parent — suppresses own data-appearance/data-variant, uses parent's CSS variables | |
link | Appearance | Link color appearance (blue, for hyperlinks) | |
primary | Appearance | ✓ | Primary color appearance (gray) |
secondary | Appearance | Secondary color appearance (gray) | |
success | Appearance | Success color appearance (green) | |
tertiary | Appearance | Tertiary color appearance | |
warning | Appearance | Warning color appearance (amber) | |
flex1 | Flex | Take up remaining space (= `flex-1`, i.e. `flex: 1 1 0%`) | |
flexAuto | Flex | Grow but respect intrinsic size (= `flex-auto`, i.e. `flex: 1 1 auto`) | |
flexNone | Flex | Don't grow and don't shrink (= `flex-none`, i.e. `flex: none`) | |
heading | Font Family | Heading font family (defaults to sans, independently customizable via --font-heading CSS variable) | |
mono | Font Family | Monospace font family | |
sans | Font Family | Sans-serif font family (default) | |
serif | Font Family | Serif font family | |
italic | Font Style | Italic font style | |
notItalic | Font Style | Not italic (normal) font style | |
black | Font Weight | Black font weight (900) | |
bold | Font Weight | Bold font weight (700) | |
extrabold | Font Weight | Extra bold font weight (800) | |
extralight | Font Weight | Extra light font weight (200) | |
light | Font Weight | Light font weight (300) | |
medium | Font Weight | Medium font weight (500) | |
normal | Font Weight | Normal font weight (400) | |
semibold | Font Weight | Semibold font weight (600) | |
thin | Font Weight | Thin font weight (100) | |
noPadding | Padding | ✓ | Disable internal padding |
padding | Padding | Enable internal padding | |
paddingX | Padding | Enable only horizontal padding | |
paddingY | Padding | Enable only vertical padding | |
pill | Shape | Fully rounded corners (circular) | |
pill | Shape | Fully rounded corners (circular) | |
rounded | Shape | ✓ | Medium rounded corners (default) |
rounded | Shape | ✓ | Medium rounded corners (default) |
sharp | Shape | No rounded corners (square) | |
sharp | Shape | No rounded corners (square) | |
noShrink | Shrink | Prevent the flex item from shrinking below its content size (= `shrink-0`) | |
lg | Size | Large size | |
md | Size | ✓ | Medium size (default) |
sm | Size | Small size | |
xl | Size | Extra large size | |
xs | Size | Extra small size | |
textCenter | Text Align | Align text to center | |
textJustify | Text Align | Justify text | |
textLeft | Text Align | Align text to left | |
textRight | Text Align | Align text to right | |
lineThrough | Text Decoration | Add strikethrough/line-through decoration across text | |
noUnderline | Text Decoration | Remove text decoration (no underline, strikethrough, etc.) | |
overline | Text Decoration | Add overline decoration above text | |
underline | Text Decoration | Add underline decoration below text | |
capitalize | Text Transform | Capitalize first letter of each word | |
lowercase | Text Transform | Transform text to lowercase | |
normalCase | Text Transform | Normal text case (no transformation) | |
uppercase | Text Transform | Transform text to uppercase | |
lineClamp2 | Truncate | Truncate at 2 lines with ellipsis | |
lineClamp3 | Truncate | Truncate at 3 lines with ellipsis | |
lineClamp4 | Truncate | Truncate at 4 lines with ellipsis | |
lineClamp5 | Truncate | Truncate at 5 lines with ellipsis | |
noTruncate | Truncate | Remove truncation | |
truncate | Truncate | Single line truncation with ellipsis | |
filled | Variant | Filled variant - solid background with contrasting text color | |
ghost | Variant | Ghost variant - transparent background, no border, appearance-colored text, tinted hover background | |
outline | Variant | ✓ | Outline variant - transparent background with border and colored text (default) |
Layout & utility props (gap, padding, hide, items, justify, ...) — documented on Common Props
| Prop | Category | Default | Description |
|---|---|---|---|
border | Border | Enable border on all sides | |
borderB | Border | Enable border on bottom | |
borderL | Border | Enable border on left | |
borderR | Border | Enable border on right | |
borderT | Border | Enable border on top | |
borderX | Border | Enable border on left and right | |
borderY | Border | Enable border on top and bottom | |
noBorder | Border | Disable all borders | |
block | Display | Block display - takes full width, new line | |
contents | Display | Contents display - element's box is removed, children display as if parent didn't exist | |
flex | Display | ✓ | Flex display - flexbox container |
grid | Display | Grid display - CSS grid container | |
hidden | Display | Hidden display - element is not visible | |
inline | Display | Inline display - flows with text | |
inlineBlock | Display | Inline-block display - inline but with block properties | |
inlineFlex | Display | Inline-flex display - inline flexbox container | |
inlineGrid | Display | Inline-grid display - inline grid container | |
table | Display | Table display - behaves like table element | |
tableCell | Display | Table-cell display - behaves like td element | |
column | Flex Direction | ✓ | Flex direction column (vertical) |
columnReverse | Flex Direction | Flex direction column-reverse | |
row | Flex Direction | Flex direction row (horizontal) | |
rowReverse | Flex Direction | Flex direction row-reverse | |
gap | Gap | ✓ | Enable gap spacing between children |
noGap | Gap | Disable gap spacing | |
hAuto | Height | Set height to auto | |
hFit | Height | Set height to fit-content | |
hFull | Height | Set height to 100% | |
hScreen | Height | Set height to 100vh (viewport height), removes max-height constraint | |
desktopHide | Hide | Hide element on desktop devices and below (max-desktop: 80rem) | |
mobileHide | Hide | Hide element on mobile devices and below (max-mobile: 48rem) | |
tabletHide | Hide | Hide element on tablet devices and below (max-tablet: 64rem) | |
itemsBaseline | Items | Align items to baseline | |
itemsCenter | Items | Align items to center | |
itemsEnd | Items | Align items to end (bottom/right) | |
itemsStart | Items | Align items to start (top/left) | |
itemsStretch | Items | Stretch items to fill container | |
justifyAround | Justify | Distribute items with space around them | |
justifyBaseline | Justify | Align items along their baseline on main axis | |
justifyBetween | Justify | Distribute items with space between them | |
justifyCenter | Justify | Center items along the main axis | |
justifyEnd | Justify | Pack items toward the end of the main axis | |
justifyEvenly | Justify | Distribute items with equal space around them | |
justifyStart | Justify | Pack items toward the start of the main axis | |
justifyStretch | Justify | Stretch items to fill the main axis | |
overflowAuto | Overflow | ✓ | Auto overflow - show scrollbars if needed |
overflowClip | Overflow | Clip overflow - hard clip without scrollbars | |
overflowHidden | Overflow | Hidden overflow - clip content without scrollbars | |
overflowScroll | Overflow | Scroll overflow - always show scrollbars | |
overflowVisible | Overflow | Visible overflow - content extends beyond bounds | |
overflowXAuto | Overflow | Auto overflow on X-axis only | |
overflowXClip | Overflow | Clip overflow on X-axis only | |
overflowXHidden | Overflow | Hidden overflow on X-axis only | |
overflowXScroll | Overflow | Scroll overflow on X-axis only | |
overflowXVisible | Overflow | Visible overflow on X-axis only | |
overflowYAuto | Overflow | Auto overflow on Y-axis only | |
overflowYClip | Overflow | Clip overflow on Y-axis only | |
overflowYHidden | Overflow | Hidden overflow on Y-axis only | |
overflowYScroll | Overflow | Scroll overflow on Y-axis only | |
overflowYVisible | Overflow | Visible overflow on Y-axis only | |
absolute | Position | Absolute positioning | |
fixed | Position | Fixed positioning | |
relative | Position | ✓ | Relative positioning |
static | Position | Static positioning | |
sticky | Position | Sticky positioning | |
responsive | Responsive | Enable responsive sizing - uses breakpoint-specific classes for font size, padding, and gap | |
reverse | Reverse | Reverse the order of children | |
noRing | Ring | Disable focus ring | |
ring | Ring | Enable focus ring | |
noShadow | Shadow | Disable drop shadow | |
shadow | Shadow | ✓ | Enable drop shadow |
transparent | Transparent | Disable background color - makes component background transparent | |
wAuto | Width | Set width to auto | |
wFit | Width | Set width to fit-content | |
wFull | Width | ✓ | Set width to 100% |
wScreen | Width | Set width to 100vw (viewport width), removes max-width constraint | |
flexNoWrap | Wrap | Force flex items to stay on single line (may overflow) | |
flexWrap | Wrap | Allow flex items to wrap to new lines when container is too narrow | |
flexWrapReverse | Wrap | Wrap flex items in reverse order (last items wrap first) |