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".

Basic Modal

A confirmation dialog with title, text, and action buttons. Modal includes focus trapping, scroll lock, and ARIA attributes (role="dialog", aria-modal="true") by default.

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>

Modal Sizes

Use size props to control the modal content width.

<Modal open={open} onClose={onClose} sm>Small modal</Modal>
<Modal open={open} onClose={onClose} lg>Large modal</Modal>

Form Modal

Modals can contain forms with inputs, labels, and checkboxes. Focus trapping keeps Tab navigation within the modal.

<Modal open={open} onClose={onClose}>
  <Stack>
    <Label>Name</Label>
    <Input placeholder="Enter your name" />
    <Checkbox>I agree to the terms</Checkbox>
  </Stack>
</Modal>

Blur Overlay

Pass overlayProps={{ blur: true }} to add a backdrop blur effect to the overlay behind the modal.

<Modal open={open} onClose={onClose} overlayProps={{ blur: true }}>
  <Text>Blurred background</Text>
</Modal>

Non-dismissible Modal

Disable closeOnOverlayClick and closeOnEscape to prevent closing the modal without explicit user action.

<Modal
  open={open}
  onClose={onClose}
  closeOnOverlayClick={false}
  closeOnEscape={false}
>
  <Text>Must click a button to close</Text>
</Modal>

Modal Appearances

Apply appearance and variant props to style the modal content area.

<Modal open={open} onClose={onClose} primary filled>Primary modal</Modal>
<Modal open={open} onClose={onClose} danger filled>Danger modal</Modal>

Use ModalHeader, ModalBody, ModalFooter, and ModalCloseButton for full control over the modal layout. When any of these sub-components are detected as direct children, the modal switches to compound mode and renders them as-is without auto-wrapping.

import { Modal, ModalHeader, ModalBody, ModalFooter, ModalCloseButton, Button, Title, Input, Label, Stack, Row } from "@vaneui/ui";

<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>
    <Row justifyEnd>
      <Button sm onClick={() => setOpen(false)}>Cancel</Button>
      <Button sm primary filled onClick={() => setOpen(false)}>Save</Button>
    </Row>
  </ModalFooter>
</Modal>

Convenience Props

Use the title, footer, and withCloseButton shorthand props to quickly set up a structured modal without manually composing sub-components. When title is set, a close button is shown by default (controlled by withCloseButton). The body content is passed as children.

import { Modal, Button, Text, Row } from "@vaneui/ui";

<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>

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. This is 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 includes built-in accessibility features that are enabled by default. You can customize them as needed:

Prop	Default	Description
`scrollLock`	`true`	Lock body scroll when modal is open
`focusTrap`	`true`	Trap Tab/Shift+Tab focus inside modal
`returnFocus`	`true`	Return focus to trigger element on close
`initialFocus`	—	Ref to element that receives focus on open
`portal`	`true`	Render in a portal (document.body)
`keepMounted`	`false`	Keep DOM node when closed
`noAnimation`	`false`	Disable enter/exit transitions
`transitionDuration`	`200`	Animation duration in ms

Modal also renders with role="dialog" and aria-modal="true" automatically.

{/* 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

Font Weight

Font weight props for controlling text weight

thin

Thin font weight (100)

extralight

Extra light font weight (200)

light

Light font weight (300)

normal

Normal font weight (400)

medium

Medium font weight (500)

semibold

Semibold font weight (600)

bold

Bold font weight (700)

extrabold

Extra bold font weight (800)

black

Black font weight (900)

Font Style

Font style props for controlling text style

italic

Italic font style

notItalic

Not italic (normal) font style

Text Decoration

Text decoration props for controlling text underline/strikethrough

underline

Add underline decoration below text

lineThrough

Add strikethrough/line-through decoration across text

noUnderline

Remove text decoration (no underline, strikethrough, etc.)

overline

Add overline decoration above text

Text Transform

Text transform props for controlling text case

uppercase

Transform text to uppercase

lowercase

Transform text to lowercase

capitalize

Capitalize first letter of each word

normalCase

Normal text case (no transformation)

Font Family

Font family props for controlling text font

sans

Sans-serif font family (default)

serif

Serif font family

mono

Monospace font family

heading

Heading font family (defaults to sans, independently customizable via --font-heading CSS variable)

Text Align

Text alignment props for controlling text position

textLeft

Align text to left

textCenter

Align text to center

textRight

Align text to right

textJustify

Justify text

Truncate

Truncate props for controlling text overflow with ellipsis

truncate

Single line truncation with ellipsis

lineClamp2

Truncate at 2 lines with ellipsis

lineClamp3

Truncate at 3 lines with ellipsis

lineClamp4

Truncate at 4 lines with ellipsis

lineClamp5

Truncate at 5 lines with ellipsis

noTruncate

Remove truncation

Size

Size props for controlling component dimensions

Extra small size

Small size

Medium size (default)

Large size

Extra large size

Hide

Hide props for responsive element visibility

mobileHide

Hide element on mobile devices and below (max-mobile: 48rem)

tabletHide

Hide element on tablet devices and below (max-tablet: 64rem)

desktopHide

Hide element on desktop devices and below (max-desktop: 80rem)

Items

Items props for controlling flex item alignment (align-items)

itemsStart

Align items to start (top/left)

itemsEnd

Align items to end (bottom/right)

itemsCenter

Align items to center

itemsBaseline

Align items to baseline

itemsStretch

Stretch items to fill container

Justify

Justify props for controlling flex content alignment (justify-content)

justifyStart

Pack items toward the start of the main axis

justifyEnd

Pack items toward the end of the main axis

justifyCenter

Center items along the main axis

justifyBetween

Distribute items with space between them

justifyAround

Distribute items with space around them

justifyEvenly

Distribute items with equal space around them

justifyStretch

Stretch items to fill the main axis

justifyBaseline

Align items along their baseline on main axis

Position

Position props for controlling CSS position property

relative

Relative positioning

absolute

Absolute positioning

fixed

Fixed positioning

sticky

Sticky positioning

static

Static positioning

Display

Display props for controlling CSS display property

inline

Inline display - flows with text

block

Block display - takes full width, new line

inlineBlock

Inline-block display - inline but with block properties

flex

Flex display - flexbox container

inlineFlex

Inline-flex display - inline flexbox container

grid

Grid display - CSS grid container

inlineGrid

Inline-grid display - inline grid container

contents

Contents display - element's box is removed, children display as if parent didn't exist

table

Table display - behaves like table element

tableCell

Table-cell display - behaves like td element

hidden

Hidden display - element is not visible

Overflow

Overflow props for controlling content overflow behavior

overflowAuto

Auto overflow - show scrollbars if needed

overflowHidden

Hidden overflow - clip content without scrollbars

overflowClip

Clip overflow - hard clip without scrollbars

overflowVisible

Visible overflow - content extends beyond bounds

overflowScroll

Scroll overflow - always show scrollbars

overflowXAuto

Auto overflow on X-axis only

overflowYAuto

Auto overflow on Y-axis only

overflowXHidden

Hidden overflow on X-axis only

overflowYHidden

Hidden overflow on Y-axis only

overflowXClip

Clip overflow on X-axis only

overflowYClip

Clip overflow on Y-axis only

overflowXVisible

Visible overflow on X-axis only

overflowYVisible

Visible overflow on Y-axis only

overflowXScroll

Scroll overflow on X-axis only

overflowYScroll

Scroll overflow on Y-axis only

Wrap

Wrap props for controlling flex wrapping behavior

flexWrap

Allow flex items to wrap to new lines when container is too narrow

flexNoWrap

Force flex items to stay on single line (may overflow)

flexWrapReverse

Wrap flex items in reverse order (last items wrap first)

Gap

Gap props for controlling spacing between children

gap

Enable gap spacing between children

noGap

Disable gap spacing

Flex Direction

Flex direction props for controlling flex layout direction

row

Flex direction row (horizontal)

column

Flex direction column (vertical)

rowReverse

Flex direction row-reverse

columnReverse

Flex direction column-reverse

Reverse

Reverse props for reversing child order

reverse

Reverse the order of children

Appearance

Appearance props for controlling component colors

primary

Primary color appearance (gray)

brand

Brand color appearance (blue)

accent

Accent color appearance (rose)

secondary

Secondary color appearance (gray)

tertiary

Tertiary color appearance

success

Success color appearance (green)

danger

Danger color appearance (red)

warning

Warning color appearance (amber)

info

Info color appearance (cyan)

link

Link color appearance (blue, for hyperlinks)

inherit

Inherit appearance from parent — suppresses own data-appearance/data-variant, uses parent's CSS variables

Border

Border props for controlling component borders

border

Enable border on all sides

borderT

Enable border on top

borderB

Enable border on bottom

borderL

Enable border on left

borderR

Enable border on right

borderX

Enable border on left and right

borderY

Enable border on top and bottom

noBorder

Disable all borders

Shadow

Shadow props for controlling drop shadows

shadow

Enable drop shadow

noShadow

Disable drop shadow

Ring

Ring props for controlling focus rings

ring

Enable focus ring

noRing

Disable focus ring

Shape

Shape props for controlling component border radius

pill

Fully rounded corners (circular)

sharp

No rounded corners (square)

rounded

Medium rounded corners (default)

Padding

Padding props for controlling internal spacing

padding

Enable internal padding

paddingX

Enable only horizontal padding

paddingY

Enable only vertical padding

noPadding

Disable internal padding

Shape

Shape props for controlling component border radius

pill

Fully rounded corners (circular)

sharp

No rounded corners (square)

rounded

Medium rounded corners (default)

Variant

Variant props for controlling component style variations

filled

Filled variant - solid background with contrasting text color

outline

Outline variant - transparent background with border and colored text (default)

Width

Width props for controlling component width

wFull

Set width to 100%

wFit

Set width to fit-content

wAuto

Set width to auto

wScreen

Set width to 100vw (viewport width), removes max-width constraint

Height

Height props for controlling component height

hFit

Set height to fit-content

hFull

Set height to 100%

hAuto

Set height to auto

hScreen

Set height to 100vh (viewport height), removes max-height constraint

Transparent

Transparent prop for disabling background color

transparent

Disable background color - makes component background transparent

Responsive

Responsive prop for enabling breakpoint-specific sizing

responsive

Enable responsive sizing - uses breakpoint-specific classes for font size, padding, and gap