Dialog

Overlay & Surface
stable

Modal overlay dialog built on OrigamOverlay and OrigamCard. Supports activator slot, focus trap, scrollable mode, fullscreen, size variants, and status icons.

Structure

Anatomy

Visual breakdown of the component's internal structure with BEM class call-outs.

Anatomy of OrigamDialogSchematic of the Dialog component showing overlay wrapper, card body, header, content, and footer zones. origam-overlay (scrim) header — prepend | title | subtitle | append (close btn) #content slot + isRead sentinel footer — action buttons 1 2 3 4
Anatomy of <origam-dialog> — 4 zones: ① overlay scrim, ② card header (prepend / title / append), ③ scrollable content body, ④ footer for actions.
1.origam-overlay (scrim)
Full-viewport overlay managed by OrigamOverlay. Blocks interaction with the page and handles click-outside / Escape key.
2.origam-card (header)
Card header zone with prepend (status icon), title (aria-labelledby target), subtitle, and append (close button).
3.origam-card__content
Scrollable content body. Contains the #content slot plus an invisible IntersectionObserver sentinel that fires isRead when scrolled into view.
4.origam-card__footer
Footer area for action buttons. Typically Cancel and Confirm. Fixed at the bottom in scrollable mode.

API

Props

All props accepted by this component, with their type, default value and description.

fullscreen
boolean
false
Expands the dialog to cover the full viewport (100vw × 100vh), with border-radius and margin reset to 0.
retainFocus
boolean
true
Keeps keyboard focus trapped inside the dialog while it is open. Cycles between the first and last focusable element on Tab.
scrollable
boolean
false
Enables vertical scrolling inside the dialog body while the header and footer remain fixed.
size
'default'
Controls the dialog width via size tokens (xs: 320px, sm: 400px, md: 720px, lg: 960px, xl: 1080px).
closeLabel
string
id
string
class
string | Array<string> | object
style
string | Array<string> | object | StyleValue
absolute
boolean
closeOnBack
boolean
true
Closes the dialog on browser back navigation.
contentClass
string | Array<string>
CSS class(es) applied to the overlay content wrapper (.origam-overlay__content).
contentProps
any
disabled
boolean
false
Disables the activator and prevents the dialog from opening.
noClickAnimation
boolean
modelValue
boolean
v-model binding for the open/close state of the dialog.
zIndex
number | string
2400
z-index of the overlay layer. Defaults to 2400 (above most overlays).
disableGlobalStack
boolean
persistent
boolean
false
When true, clicking outside the dialog or pressing Escape does not close it. Useful for required confirmation dialogs.
height
number | string
maxHeight
number | string
maxWidth
number | string
minHeight
number | string
minWidth
number | string
width
number | string
target
'parent' | 'cursor' | TAnyString | Element | ComponentPublicInstance | [x: number, y: number] | undefined
activator
'parent' | 'cursor' | TAnyString | Element | ComponentPublicInstance
activatorProps
any
Extra props merged onto the activator element. Dialog automatically adds aria-haspopup="dialog" and aria-expanded.
openOnClick
boolean
true
Opens the dialog when the activator is clicked. Defaults to true (Dialog overrides OrigamOverlay's default to keep activator clicks working).
openOnContextMenu
boolean
openOnHover
boolean
openOnFocus
boolean
closeOnContentClick
boolean
closeDelay
number | string
openDelay
number | string
locationStrategy
TLocationStrategy | TLocationStrategyFn
location
TAnchor
origin
TAnchor | 'auto' | 'overlap'
'center center'
transform-origin for the enter/leave transition.
offset
number | string | Array<number>
viewportMargin
number
scrollStrategy
TScrollStrategy | TScrollStrategyFn
'block'
Scroll behavior while the dialog is open. "block" prevents page scrolling.
contained
boolean
eager
boolean
transition
boolean | string | TTransitionProps
OrigamTranslateScale
Transition used when the dialog enters/leaves. Defaults to OrigamTranslateScale.
scrim
boolean | string
attach
boolean | string | Element | null
contentDisplay
TCardContentDisplay
flat
boolean
image
string
link
boolean
subtitle
string | number
Subtitle rendered below the title in the card header.
text
string | number
Body text rendered inside the card text slot.
title
string | number
Dialog title rendered in the card header. Referenced by aria-labelledby for accessible naming.
type
TCardType
titleId
string
tag
string
border
boolean | number | string | TDirectionBoth | Array<TDirectionBoth>
borderTop
boolean | number | string
borderLeft
boolean | number | string
borderBottom
boolean | number | string
borderRight
boolean | number | string
borderBlock
boolean | number | string
borderInline
boolean | number | string
borderInlineStart
boolean | number | string
borderInlineEnd
boolean | number | string
borderBlockStart
boolean | number | string
borderBlockEnd
boolean | number | string
borderColor
string
borderStyle
string
borderTopColor
TColor
borderRightColor
TColor
borderBottomColor
TColor
borderLeftColor
TColor
borderInlineStartColor
TColor
borderInlineEndColor
TColor
borderBlockStartColor
TColor
borderBlockEndColor
TColor
color
Intent or custom color applied to the card surface (forwarded to OrigamCard).
bgColor
TColor
density
TDensity
elevation
TElevation
Box-shadow elevation token forwarded to the inner card.
loading
TLoadingValue
loadingText
string
position
TPosition
top
number | string
bottom
number | string
left
number | string
right
number | string
Border-radius token for the inner card (overrides --origam-dialog---border-radius).
roundedTopRight
boolean | number | string
roundedTopLeft
boolean | number | string
roundedBottomLeft
boolean | number | string
roundedBottomRight
boolean | number | string
roundedStartStart
boolean | number | string
roundedStartEnd
boolean | number | string
roundedEndStart
boolean | number | string
roundedEndEnd
boolean | number | string
margin
boolean | number | string
marginTop
boolean | number | string
marginLeft
boolean | number | string
marginBottom
boolean | number | string
marginRight
boolean | number | string
marginBlock
boolean | number | string
marginInline
boolean | number | string
marginInlineStart
boolean | number | string
marginInlineEnd
boolean | number | string
marginBlockStart
boolean | number | string
marginBlockEnd
boolean | number | string
padding
boolean | number | string
paddingTop
boolean | number | string
paddingLeft
boolean | number | string
paddingBottom
boolean | number | string
paddingRight
boolean | number | string
paddingBlock
boolean | number | string
paddingInline
boolean | number | string
paddingInlineStart
boolean | number | string
paddingInlineEnd
boolean | number | string
paddingBlockStart
boolean | number | string
paddingBlockEnd
boolean | number | string
href
string
replace
boolean
to
RouteLocationRaw
exact
boolean
ripple
boolean | { class: string }
appendAvatar
string
appendIcon
TIcon
prependAvatar
string
prependIcon
TIcon
prependAriaLabel
string
appendAriaLabel
string
active
boolean | IStateEffectConfig
activeClass
string
hover
boolean | IStateEffectConfig
hoverClass
string
status
Semantic status (success, warning, danger, info) that resolves the header prepend icon and applies a status CSS class.
statusIconPosition
TStatusPosition
icon
Custom MDI icon shown in the header-prepend slot. Overrides the status icon when both are set.

API

Slots

Content slots exposed by this component.

#activator
Element that triggers the dialog. Bind the provided props object onto your trigger element to wire aria-haspopup, aria-expanded and the click handler.
#default
Replaces the entire dialog body (including the default OrigamCard). Use when you need a completely custom modal layout.
#loader
Custom loading indicator forwarded to the inner OrigamCard loader slot.
#header
Replaces the entire card header with custom content.
#header-append
Content after the title row. Defaults to the close icon button (mdi-close).
#header-prepend
Content before the dialog title. By default renders the status/icon when set.
#header-title
Custom title content. The titleId slot prop should be used as the element id so aria-labelledby resolves correctly.
#header-subtitle
Custom subtitle content below the title in the header.
#header-content
Extra content area inside the header (between subtitle and append).
#asset
Visual asset (image, illustration) rendered above the text content inside the card.
#text
Body text content forwarded to the inner card text slot.
#content
Main dialog content. Scrollable when scrollable=true. The isRead sentinel div is appended after this slot.
#footer
Footer area typically used for action buttons (Cancel / Confirm).

API

Emits

Events emitted by this component.

@isRead
boolean
Fired the first time the bottom of the dialog content intersects the viewport (scroll-to-read pattern for ToS / consent dialogs). Payload is always true.
@update:modelValue
any
Fired when the dialog open/close state changes.
@click:outside
MouseEvent
Fired when the user clicks outside the dialog content area. Default behavior closes the dialog unless persistent=true.

API

Exposed members

Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.

<T extends object>(props: T, exclude?: string[]) => Partial<T>
Utility to forward a filtered subset of props to inner OrigamOverlay or OrigamCard instances.
Ref<string>
Reactive CSS string generated from dialogStyles. Used by OrigamDefaultsProvider for style injection.
string
Unique style-sheet ID for this dialog instance.
() => void
Injects the computed style sheet. Called automatically on mount.
() => void
Removes the injected style sheet. Called automatically on unmount.
Ref<boolean>
True once the style sheet has been injected.
HTMLElement | undefined
Reference to the overlay content element forwarded from the inner OrigamOverlay ref.
HTMLElement | undefined
Reference to the activator element forwarded from the inner OrigamOverlay ref.
boolean
True when this dialog is the topmost open overlay in the global stack.

Customisation

CSS variables

CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.

Dialog width. Overridden per size class (xs: 320px → xl: 1080px) and set to 100vw in fullscreen mode.
Maximum dialog height. Resolves to 100vh in fullscreen mode.
Maximum dialog width.
Border radius applied to the overlay content wrapper. Reset to 0 in fullscreen mode.
Box shadow applied to the dialog surface for depth.
Width token for size="x-small".
Width token for size="small".
Width token for size="default".
Width token for size="large".
Width token for size="x-large".

Inclusion

Accessibility

ARIA roles, keyboard navigation and focus management. Sourced from the real component template.

ARIA roles

dialog

Keyboard interactions

Keyboard interactions
KeyAction
EscapeCloses the dialog (unless persistent=true).
TabCycles focus through focusable elements inside the dialog. When retainFocus=true, Tab wraps from last to first element.
Shift+TabCycles focus backwards. Wraps from first to last element when retainFocus=true.

Notes

  • The inner OrigamCard renders role="dialog" and aria-modal="true". The title element is linked via aria-labelledby using the auto-generated dialogTitleId.
  • On open, focus moves to the overlay content element. On close, focus returns to the activator element.
  • The activator element automatically receives aria-haspopup="dialog" and aria-expanded bound to the open state.
  • When persistent=true, Escape and click-outside do not close the dialog. Use this only for critical flows (e.g., unsaved changes warning).

Foundation

Design tokens

Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.

Source
color
var(--origam-color__surface---raised)
Dialog surface background. Uses the raised surface semantic color.
dimension
var(--origam-radius---lg)
Border radius applied to the dialog content wrapper. Reset to 0 in fullscreen mode.
shadow
var(--origam-shadow---xl)
Elevation shadow for the dialog surface.
number
var(--origam-zIndex---modal)
z-index of the dialog overlay (default: 2400).
dimension
720px
Default dialog width (size="default").
duration
var(--origam-motion__duration---medium)
Enter/leave transition duration.
dimension
var(--origam-space---4)
Padding inside the dialog header zone.
dimension
var(--origam-space---6)
Horizontal padding of the dialog body content.

Interactive

Playground

Edit props live and see the component update in real time. The generated code snippet updates as you change values.

Rendering the live preview…

Usage

Examples

Ready-to-paste code snippets for your templates.

Basic dialog with activator

vue

Fullscreen dialog

vue

Confirmation dialog (DialogConfirmation)

vue

Ecosystem

Family

Components from the same folder that share conventions and often compose together.