Dialog
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.
<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.
- fullscreenbooleanfalse
- Expands the dialog to cover the full viewport (100vw × 100vh), with border-radius and margin reset to 0.
- retainFocusbooleantrue
- Keeps keyboard focus trapped inside the dialog while it is open. Cycles between the first and last focusable element on Tab.
- scrollablebooleanfalse
- Enables vertical scrolling inside the dialog body while the header and footer remain fixed.
- Controls the dialog width via size tokens (xs: 320px, sm: 400px, md: 720px, lg: 960px, xl: 1080px).
- closeLabelstring
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- absoluteboolean
- closeOnBackbooleantrue
- Closes the dialog on browser back navigation.
- contentClassstring | Array<string>
- CSS class(es) applied to the overlay content wrapper (.origam-overlay__content).
- contentPropsany
- disabledbooleanfalse
- Disables the activator and prevents the dialog from opening.
- noClickAnimationboolean
- modelValueboolean
- v-model binding for the open/close state of the dialog.
- zIndexnumber | string2400
- z-index of the overlay layer. Defaults to 2400 (above most overlays).
- disableGlobalStackboolean
- persistentbooleanfalse
- When true, clicking outside the dialog or pressing Escape does not close it. Useful for required confirmation dialogs.
- heightnumber | string
- maxHeightnumber | string
- maxWidthnumber | string
- minHeightnumber | string
- minWidthnumber | string
- widthnumber | string
- target'parent' | 'cursor' | TAnyString | Element | ComponentPublicInstance | [x: number, y: number] | undefined
- activator'parent' | 'cursor' | TAnyString | Element | ComponentPublicInstance
- activatorPropsany
- Extra props merged onto the activator element. Dialog automatically adds aria-haspopup="dialog" and aria-expanded.
- openOnClickbooleantrue
- Opens the dialog when the activator is clicked. Defaults to true (Dialog overrides OrigamOverlay's default to keep activator clicks working).
- openOnContextMenuboolean
- openOnHoverboolean
- openOnFocusboolean
- closeOnContentClickboolean
- closeDelaynumber | string
- openDelaynumber | string
- locationStrategyTLocationStrategy | TLocationStrategyFn
- locationTAnchor
- originTAnchor | 'auto' | 'overlap''center center'
- transform-origin for the enter/leave transition.
- offsetnumber | string | Array<number>
- viewportMarginnumber
- scrollStrategyTScrollStrategy | TScrollStrategyFn'block'
- Scroll behavior while the dialog is open. "block" prevents page scrolling.
- containedboolean
- eagerboolean
- transitionboolean | string | TTransitionPropsOrigamTranslateScale
- Transition used when the dialog enters/leaves. Defaults to OrigamTranslateScale.
- scrimboolean | string
- attachboolean | string | Element | null
- contentDisplayTCardContentDisplay
- flatboolean
- imagestring
- linkboolean
- subtitlestring | number
- Subtitle rendered below the title in the card header.
- textstring | number
- Body text rendered inside the card text slot.
- titlestring | number
- Dialog title rendered in the card header. Referenced by aria-labelledby for accessible naming.
- typeTCardType
- titleIdstring
- tagstring
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>
- borderTopboolean | number | string
- borderLeftboolean | number | string
- borderBottomboolean | number | string
- borderRightboolean | number | string
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- color
- Intent or custom color applied to the card surface (forwarded to OrigamCard).
- bgColorTColor
- densityTDensity
- elevationTElevation
- Box-shadow elevation token forwarded to the inner card.
- loadingTLoadingValue
- loadingTextstring
- positionTPosition
- topnumber | string
- bottomnumber | string
- leftnumber | string
- rightnumber | string
- Border-radius token for the inner card (overrides --origam-dialog---border-radius).
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- hrefstring
- replaceboolean
- toRouteLocationRaw
- exactboolean
- rippleboolean | { class: string }
- appendAvatarstring
- appendIconTIcon
- prependAvatarstring
- prependIconTIcon
- prependAriaLabelstring
- appendAriaLabelstring
- activeboolean | IStateEffectConfig
- activeClassstring
- hoverboolean | IStateEffectConfig
- hoverClassstring
- status
- Semantic status (success, warning, danger, info) that resolves the header prepend icon and applies a status CSS class.
- statusIconPositionTStatusPosition
- 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.
- @isReadboolean
- 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:modelValueany
- Fired when the dialog open/close state changes.
- @click:outsideMouseEvent
- 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
Keyboard interactions
| Key | Action |
|---|---|
| Escape | Closes the dialog (unless persistent=true). |
| Tab | Cycles focus through focusable elements inside the dialog. When retainFocus=true, Tab wraps from last to first element. |
| Shift+Tab | Cycles 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.
- colorvar(--origam-color__surface---raised)
- Dialog surface background. Uses the raised surface semantic color.
- dimensionvar(--origam-radius---lg)
- Border radius applied to the dialog content wrapper. Reset to 0 in fullscreen mode.
- shadowvar(--origam-shadow---xl)
- Elevation shadow for the dialog surface.
- numbervar(--origam-zIndex---modal)
- z-index of the dialog overlay (default: 2400).
- dimension720px
- Default dialog width (size="default").
- durationvar(--origam-motion__duration---medium)
- Enter/leave transition duration.
- dimensionvar(--origam-space---4)
- Padding inside the dialog header zone.
- dimensionvar(--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
Fullscreen dialog
Confirmation dialog (DialogConfirmation)
Ecosystem
Family
Components from the same folder that share conventions and often compose together.