Skip to content

OrigamDialog ​

<OrigamDialog> is a modal dialog built on OrigamOverlay and OrigamCard. It manages focus trapping, ARIA attributes, scroll blocking, and keyboard dismissal (ESC). Use it for confirmation dialogs, forms, and informational messages.

Basic usage ​

vue
<template>
    <OrigamDialog v-model="open" title="Hello">
        <template #activator="{ props: a }">
            <OrigamBtn v-bind="a">Open</OrigamBtn>
        </template>
        <template #content>Dialog body text.</template>
        <template #footer>
            <OrigamBtn @click="open = false">Close</OrigamBtn>
        </template>
    </OrigamDialog>
</template>

Props ​

⛔ Added 2026-08-31 (issue #419) — this component had no Props table at all despite exposing ~20 props through IOverlayProps / ICardProps / IStatusProps. Grouped to mirror the story's own control groups (packages/stories/components/stories/Dialog/OrigamDialog.story.vue, Design + Functional Variants) rather than re-deriving an ad-hoc grouping.

GroupPropTypeDescription
BehaviourfullscreenbooleanDialog fills the viewport, no margin/rounding.
retainFocusbooleanLoops focus inside the dialog with Tab / Shift+Tab. Default true.
persistentboolean (from IOverlayProps)Disables closing on ESC / outside click.
disabledboolean (from IOverlayProps)Prevents the activator from opening the dialog.
Sizingsize'x-small' | 'small' | 'default' | 'large' | 'x-large'Preset width rung — see --origam-dialog---width-* tokens.
density(from ICardProps)Forwarded to the inner <OrigamCard>.
Colorcolor / bgColorTIntent | string (from ICardProps)Forwarded to the inner <OrigamCard>.
Shaperounded, elevation, flat(from ICardProps)Forwarded to the inner <OrigamCard>.
Borderborder, borderColor, borderStyle(from ICardProps)Forwarded to the inner <OrigamCard>.
Statusstatus, statusIconPosition(from IStatusProps)Built-in status icon — see Status / icon.
IconsprependIcon, appendIcon, iconTIcon (from ICardProps)Forwarded to the inner <OrigamCard> header.
Contenttitle, subtitle, text, imagestring (from ICardProps)Forwarded to the inner <OrigamCard>.
Dimensionwidth, heightnumber | string (from IOverlayProps / IDimensionProps)Sizes the content container.
AccessibilitycloseLabelstringAccessible name (locale key) of the built-in close button — see Accessibility.

IDialogProps also extends the full IOverlayProps surface (activator, location strategy, scroll strategy, lazy mount, transition, scrim — see the OrigamOverlay doc) and the full ICardProps surface beyond what's listed above — this table covers the props exercised by the component's own story, not every inherited prop.

Fullscreen ​

vue
<template>
    <OrigamDialog v-model="open" fullscreen title="Full screen dialog">…</OrigamDialog>
</template>

Scrolling ​

The dialog as a whole scrolls — .origam-overlay__content, the box that carries the --origam-dialog---max-height ceiling, is also the scrollport (overflow-y: auto). Header, asset, content and footer scroll together. There is no prop to configure this, and none is needed.

Why the ceiling and the scroll sit on the same box — issue #563

.origam-overlay__content is position: absolute with an auto height, so the max-height: 100% the dialog puts on .origam-card resolves to none: the card grows without a ceiling. Before the fix the overlay was overflow: visible, so it let the card spill off screen and nothing scrolled — not the card, not .origam-card__content, and not the document (scrollStrategy: 'block'). Measured in Chromium (Design dialog, 900 px added to #footer): card overflow hidden, clientHeight 1047 === scrollHeight 1047; footer 459 px below the viewport with zero scrollable ancestors. The &--fullscreen branch already declared overflow-y: auto; the default mode now matches it. Geometry after: the overlay reports clientHeight 564 / scrollHeight 1700, and the footer is fully reachable by wheel.

A tall #asset is clipped by OrigamCard, not by the dialog

.origam-card__asset declares aspect-ratio: 16 / 9; overflow: hidden — it is a media well. Slot content taller than that well is clipped with no scroll, and this is identical outside any dialog (measured on a standalone OrigamCard: clientHeight 334 / scrollHeight 1720, no scrollable ancestor). Making the dialog scroll does not change it. Size the asset, or put the tall content in #content.

scrollable was removed — issue #419

<OrigamDialog> used to declare a scrollable boolean. It emitted an origam-dialog--scrollable modifier class that no SCSS rule in the codebase ever targeted, and the layout it claimed to enable was already applied unconditionally by the rules above. It was therefore redundant, not merely inert: passing it, or not, produced byte-identical computed styles. Measured in Chromium, both readings of [overflow-y|overflow-x|max-height|height|display|flex-direction] across .origam-overlay__content / .origam-card / .origam-card__content:

visible|visible|calc(100% - 48px)|430px|block|row
// hidden|hidden|100%|430px|flex|column
// auto|auto|100%|330px|flex|column

Removing it changes no rendering whatsoever. It is a typed-API removal only: code passing scrollable now fails to type-check, and should simply drop the prop.

A separate defect was explicitly carved out of this decision — #563, fixed since, see the Scrolling note above. Removing scrollable neither caused nor fixed it. Do not read #419 as having settled it.

Status / icon ​

Built-in status icons via the status prop.

vue
<template>
    <OrigamDialog v-model="open" status="success" title="Saved!" />
</template>

Persistent ​

vue
<template>
    <OrigamDialog v-model="open" persistent title="Must confirm">…</OrigamDialog>
</template>

Retain focus ​

Keep focus inside the dialog. Enabled by default (retainFocus).

Slots ​

SlotSlot propsDescription
activator{ props }Element that opens the dialog. Spread props.
default{ isActive }Full content override (bypasses the inner card).
loader—Custom loader inside the card.
header—Replaces the card header.
header-prepend—Icon / avatar in the header.
header-title—Custom title markup.
header-subtitle—Custom subtitle markup.
header-content—Extra header body.
header-append—Replaces the built-in close button.
asset—Image / media banner.
text—Card text region.
content—Main scrollable body.
footer—Action row at the bottom.

Events ​

NamePayloadWhen
update:modelValuebooleanOpen / close.
isReadtrueBottom of content scrolled into view (accessibility gate).
click:outsideMouseEventClick landed outside the content (non-persistent only).

Design tokens ​

CSS variableDescription
--origam-dialog---max-heightMaximum height of the content container.
--origam-dialog---max-widthMaximum width of the content container.
--origam-dialog---border-radiusDialog border radius.
--origam-dialog---box-shadowDialog shadow.
--origam-dialog__fullscreen---max-widthFull-screen override.
--origam-dialog__fullscreen---max-heightFull-screen override.

Accessibility ​

  • role="dialog" and aria-modal="true" are set automatically.
  • aria-labelledby points at the id the inner <OrigamCard> puts on its title element, so a plain title prop is enough to give the dialog an accessible name — no extra ARIA needed. The reference is asserted to actually resolve in packages/tests/TU/components/Dialog/dialog-contract.spec.ts; a dangling aria-labelledby would leave the dialog unnamed, which is worse than no attribute at all.
  • The header's built-in close button is rendered unconditionally when the header-append slot is not supplied. It reaches <OrigamCard> through Card's OWN slot name (header.append, point notation) — the same spec pins that seam, because a name mismatch there silently drops the button and leaves the dialog closable only by ESC or an outside click.
  • aria-haspopup="dialog" and aria-expanded are applied to the activator.
  • Focus moves into the dialog on open and returns to the activator on close.
  • ESC closes non-persistent dialogs.
  • retainFocus (default true) loops focus inside the dialog with Tab / Shift+Tab.
  • closeLabel (string, default 'origam.close') is the accessible name of the built-in close button. It carries a locale key, not final text — resolved through the DS t() mechanism, the same key OrigamAlert and OrigamChip use for their own close control. A raw string that matches no key is returned unchanged, so closeLabel="Dismiss this dialog" still works for consumers who prefer to translate on their side.