Modal

An accessible dialog overlay built on Base UI. Compound component pattern with Header, Body, Footer, Title, Description, and Close. Five sizes. Five corner-rounding options. LTR and RTL support.

Playground

Installation

pnpm add @tessinaui/ui

Usage

import {
  Modal,
  ModalTrigger,
  ModalClose,
  ModalContent,
  ModalHeader,
  ModalTitle,
  ModalDescription,
  ModalBody,
  ModalFooter,
} from "@tessinaui/ui";

<Modal>
  <ModalTrigger className="...">Open</ModalTrigger>

  <ModalContent>
    <ModalHeader>
      <ModalTitle>Confirm changes</ModalTitle>
      <ModalDescription>This action cannot be undone.</ModalDescription>
    </ModalHeader>

    <ModalBody>
      <p>Additional content goes here.</p>
    </ModalBody>

    <ModalFooter>
      <ModalClose className="...">Cancel</ModalClose>
      <ModalClose className="...">Save</ModalClose>
    </ModalFooter>
  </ModalContent>
</Modal>

Showcase

API Reference

Root component. Wraps Dialog.Root from Base UI and provides size and dir context to all children.

Prop	Type	Default	Description
`size`	`"sm" \| "md" \| "lg" \| "xl" \| "full"`	`"md"`	Max-width of the popup panel
`width`	`"narrow" \| "default" \| "wide"`	`"default"`	Additional width constraint — narrow (xs), default (from size), wide (3xl)
`dir`	`"ltr" \| "rtl"`	`"ltr"`	Text direction — applied to the popup and all its children
`open`	`boolean`	—	Controlled open state
`defaultOpen`	`boolean`	`false`	Uncontrolled initial open state
`onOpenChange`	`(open: boolean) => void`	—	Callback when open state changes
`dismissible`	`boolean`	`true`	Whether clicking the backdrop or pressing Escape closes the modal
`modal`	`boolean`	`true`	Whether the dialog uses modal behavior (focus trap, scroll lock)

ModalTrigger

Re-export of Dialog.Trigger. Renders a <button> that opens the modal. Apply styles via className or swap the element via the render prop:

<ModalTrigger render={<Button />}>Open modal</ModalTrigger>

ModalContent

Renders the popup panel inside a Portal. Includes the backdrop automatically.

Prop	Type	Default	Description
`size`	`"sm" \| "md" \| "lg" \| "xl" \| "full"`	from `<Modal>`	Overrides the size from context
`width`	`"narrow" \| "default" \| "wide"`	from `<Modal>`	Overrides the width from context
`rounded`	`"full" \| "lg" \| "md" \| "sm" \| "none"`	`"full"`	Corner rounding of the panel
`className`	`string`	—	Extra classes on the popup

All other native <div> attributes (forwarded to Dialog.Popup) are accepted.

ModalHeader

Prop	Type	Default	Description
`icon`	`React.ReactNode`	—	Optional leading icon beside the title
`showClose`	`boolean`	`true`	Whether to render the built-in X close button. Set to `false` to use a custom `<ModalClose>`

ModalTitle

Renders Dialog.Title (linked to aria-labelledby). Accepts all <div> attributes plus className.

ModalDescription

Renders Dialog.Description (linked to aria-describedby). Accepts all <p> attributes plus className.

ModalBody

Scrollable content wrapper. Uses flex-1 overflow-y-auto — grows to fill space between header and footer.

ModalFooter

Flex row aligned to the end (justify-end). Accepts className to override layout if needed.

ModalClose

Re-export of Dialog.Close. Renders a <button> that closes the modal. Apply styles via className or swap via render prop:

<ModalClose render={<Button variant="secondary" />}>Cancel</ModalClose>

ModalBackdrop

Pre-styled backdrop. Included inside <ModalContent> by default — only use directly for custom layouts.

Sizes

Size	Max-width	Use case
`sm`	384 px	Confirmations, alerts, short forms
`md`	460 px	Standard dialogs (default)
`lg`	512 px	Medium-complexity forms
`xl`	576 px	Rich forms, previews
`full`	100% − 2rem	Full-screen panels

Animations

The modal uses CSS transitions driven by Base UI's data attributes:

Attribute	When applied	Effect
`data-starting-style`	First frame of opening	opacity 0, scale 0.96
(none)	Open steady state	opacity 1, scale 1
`data-ending-style`	During close animation	opacity 0, scale 0.96

The backdrop fades in/out independently with transition-opacity.

Controlled vs Uncontrolled

Uncontrolled — use <ModalTrigger> and <ModalClose> for open/close:

<Modal>
  <ModalTrigger className="...">Open</ModalTrigger>
  <ModalContent>
    <ModalFooter>
      <ModalClose className="...">Close</ModalClose>
    </ModalFooter>
  </ModalContent>
</Modal>

Controlled — manage open state yourself:

const [open, setOpen] = useState(false);

<Modal open={open} onOpenChange={setOpen}>
  <ModalTrigger onClick={() => setOpen(true)} className="...">Open</ModalTrigger>
  <ModalContent>
    <ModalFooter>
      <button onClick={() => setOpen(false)}>Cancel</button>
      <button onClick={() => { doSomething(); setOpen(false); }}>Confirm</button>
    </ModalFooter>
  </ModalContent>
</Modal>

Accessibility

Renders as role="dialog" with aria-modal="true"
<ModalTitle> is linked via aria-labelledby
<ModalDescription> is linked via aria-describedby
Focus is trapped inside the dialog when open
Scroll is locked on <body> when open
Escape key closes the modal (unless dismissible={false})
Focus returns to the trigger when the modal closes
The backdrop provides a click-outside dismiss target

Playground

Installation

pnpm add @tessinaui/ui

Usage

import {
  Modal,
  ModalTrigger,
  ModalClose,
  ModalContent,
  ModalHeader,
  ModalTitle,
  ModalDescription,
  ModalBody,
  ModalFooter,
} from "@tessinaui/ui";

<Modal>
  <ModalTrigger className="...">Open</ModalTrigger>

  <ModalContent>
    <ModalHeader>
      <ModalTitle>Confirm changes</ModalTitle>
      <ModalDescription>This action cannot be undone.</ModalDescription>
    </ModalHeader>

    <ModalBody>
      <p>Additional content goes here.</p>
    </ModalBody>

    <ModalFooter>
      <ModalClose className="...">Cancel</ModalClose>
      <ModalClose className="...">Save</ModalClose>
    </ModalFooter>
  </ModalContent>
</Modal>

Showcase

API Reference

Root component. Wraps Dialog.Root from Base UI and provides size and dir context to all children.

Prop	Type	Default	Description
`size`	`"sm" \| "md" \| "lg" \| "xl" \| "full"`	`"md"`	Max-width of the popup panel
`width`	`"narrow" \| "default" \| "wide"`	`"default"`	Additional width constraint — narrow (xs), default (from size), wide (3xl)
`dir`	`"ltr" \| "rtl"`	`"ltr"`	Text direction — applied to the popup and all its children
`open`	`boolean`	—	Controlled open state
`defaultOpen`	`boolean`	`false`	Uncontrolled initial open state
`onOpenChange`	`(open: boolean) => void`	—	Callback when open state changes
`dismissible`	`boolean`	`true`	Whether clicking the backdrop or pressing Escape closes the modal
`modal`	`boolean`	`true`	Whether the dialog uses modal behavior (focus trap, scroll lock)

ModalTrigger

Re-export of Dialog.Trigger. Renders a <button> that opens the modal. Apply styles via className or swap the element via the render prop:

<ModalTrigger render={<Button />}>Open modal</ModalTrigger>

ModalContent

Renders the popup panel inside a Portal. Includes the backdrop automatically.

Prop	Type	Default	Description
`size`	`"sm" \| "md" \| "lg" \| "xl" \| "full"`	from `<Modal>`	Overrides the size from context
`width`	`"narrow" \| "default" \| "wide"`	from `<Modal>`	Overrides the width from context
`rounded`	`"full" \| "lg" \| "md" \| "sm" \| "none"`	`"full"`	Corner rounding of the panel
`className`	`string`	—	Extra classes on the popup

All other native <div> attributes (forwarded to Dialog.Popup) are accepted.

ModalHeader

Prop	Type	Default	Description
`icon`	`React.ReactNode`	—	Optional leading icon beside the title
`showClose`	`boolean`	`true`	Whether to render the built-in X close button. Set to `false` to use a custom `<ModalClose>`

<ModalClose render={<Button variant="secondary" />}>Cancel</ModalClose>

ModalBackdrop

Pre-styled backdrop. Included inside <ModalContent> by default — only use directly for custom layouts.

Sizes

Size	Max-width	Use case
`sm`	384 px	Confirmations, alerts, short forms
`md`	460 px	Standard dialogs (default)
`lg`	512 px	Medium-complexity forms
`xl`	576 px	Rich forms, previews
`full`	100% − 2rem	Full-screen panels

Animations

The modal uses CSS transitions driven by Base UI's data attributes:

Attribute	When applied	Effect
`data-starting-style`	First frame of opening	opacity 0, scale 0.96
(none)	Open steady state	opacity 1, scale 1
`data-ending-style`	During close animation	opacity 0, scale 0.96

The backdrop fades in/out independently with transition-opacity.

Controlled vs Uncontrolled

Uncontrolled — use <ModalTrigger> and <ModalClose> for open/close:

<Modal>
  <ModalTrigger className="...">Open</ModalTrigger>
  <ModalContent>
    <ModalFooter>
      <ModalClose className="...">Close</ModalClose>
    </ModalFooter>
  </ModalContent>
</Modal>

Controlled — manage open state yourself:

const [open, setOpen] = useState(false);

<Modal open={open} onOpenChange={setOpen}>
  <ModalTrigger onClick={() => setOpen(true)} className="...">Open</ModalTrigger>
  <ModalContent>
    <ModalFooter>
      <button onClick={() => setOpen(false)}>Cancel</button>
      <button onClick={() => { doSomething(); setOpen(false); }}>Confirm</button>
    </ModalFooter>
  </ModalContent>
</Modal>

Accessibility

Renders as role="dialog" with aria-modal="true"
<ModalTitle> is linked via aria-labelledby
<ModalDescription> is linked via aria-describedby
Focus is trapped inside the dialog when open
Scroll is locked on <body> when open
Escape key closes the modal (unless dismissible={false})
Focus returns to the trigger when the modal closes
The backdrop provides a click-outside dismiss target

Modal

Playground

Installation

Usage

Showcase

API Reference

ModalTrigger

ModalContent

ModalHeader

ModalTitle

ModalDescription

ModalBody

ModalFooter

ModalClose

ModalBackdrop

Sizes

Animations

Controlled vs Uncontrolled

Accessibility

On this page

Modal

Playground

Installation

Usage

Showcase

API Reference

ModalTrigger

ModalContent

ModalHeader

ModalTitle

ModalDescription

ModalBody

ModalFooter

ModalClose

ModalBackdrop

Sizes

Animations

Controlled vs Uncontrolled

Accessibility

On this page