Dialog

A modal element that presents relevant information or actions.

The Dialog overtakes the user's entire viewport until it is dismissed, preventing mouse and keyboard interaction with other parts of the page while open. This is a significant interruption in the user experience, so this component should be used with care.

The parent component controls whether the Dialog is open via v-model:open.

A Dialog can offer two kinds of actions (represented by buttons of the appropriate type): primary action (can be progressive or destructive), and default action (typically a safe option like "cancel").

The Dialog component can either be used on its own (in which case it displays in-place, using CSS positioning and z-index to overlay the rest of the viewport), or it can be used along with Vue's built-in <teleport> component to move the component elsewhere in the DOM. This latter approach may be useful when Dialog is embedded in a large/complex page with other absolutely-positioned elements near the end of the markup.

When open, the Dialog adds a class to the document body to prevent scrolling; this is applied whether or not teleport is used.

Attributes passed to inner element

This component forwards any attributes applied by the user to the inner .cdx-dialog element, instead of applying them to the outermost backdrop element.

Demos

Configurable Dialog

Name	Value
Props
title
subtitle
hideTitle
closeButtonLabel
stackedActions
usePrimaryAction
primaryActionLabel
primaryActionType	progressivedestructive
primaryActionDisabled
useDefaultAction
defaultActionLabel
defaultActionDisabled
Slots
default
footer-text
View
Reading direction	Left to right (LTR) Right to left (RTL)

Basic example

This example includes a title, close button label (which enables the appearance of the icon-only close button), primary action, and default action.

With expandable menus

Expandable menus, like the one used by the Select component, will extend past the end of the dialog frame (instead of being cut off by it).

With overflowing content

When content in the default slot (the dialog body) is longer than the available space, the body section will scroll while the dialog header and footer will remain in view.

vue

<template>
	<cdx-button @click="open = true">
		Open dialog
	</cdx-button>
	<cdx-dialog
		v-model:open="open"
		title="Dialog with long content"
		close-button-label="Close"
		:show-dividers="true"
		:default-action="defaultAction"
		@default="open = false"
	>
		<p>
			Zesty tofu pad thai dessert cool cucumbers kung pao pepper grapefruit creamy cauliflower
			alfredo figs ghost pepper seitan asian pear. Ginger carrot spiced juice sweet potato
			Indian spiced peppermint onion hearty tofu raspberry fizz mediterranean black beans
			banana dark and stormy red amazon pepper tomato and basil balsamic vinaigrette.
		</p>
		<p>
			Cool spring earl grey latte lemon lime minty crumbled lentils bite sized kale caesar
			salad green onions açai blueberry chia seed jam. Lemongrass chili pepper fiery fruit
			Thai dragon pepper overflowing cashew vegan mediterranean luxury bowl cilantro lime
			vinaigrette smoky maple tempeh glaze green tea lime cauliflower springtime strawberry
			bean wraps coconut chocolate peanut butter dip ginger lemongrass agave green tea grain
			avocado basil pesto.
		</p>
		<p>
			Casserole pine nuts salad lemonade zest samosa habanero golden apple vinaigrette red
			curry banana bread avocado strawberries spiced peppermint blast homemade balsamic mint
			taco salsa soy milk lemon chili lentils lime mango crisp muffins mediterranean
			instant pot peach strawberry mango. Mushroom risotto chai tea summer tahini drizzle
			pistachio pesto cranberry spritzer artichoke hearts blood orange smash cookies shiitake
			mushrooms couscous soba noodles.
		</p>
		<p>
			Fall strawberry mango smoothie a delicious meal green grapes crispy iceberg lettuce
			dragon fruit street style Thai basil tacos banana bread golden cayenne pepper cayenne
			ultimate Italian pepperoncini thyme miso turmeric glazed aubergine jalapeño pumpkin.
			Creamiest leek banh mi salad rolls tempeh oranges toasted hazelnuts apricot hazelnut
			shiitake lemon tahini dressing roasted brussel sprouts cilantro kale cozy cinnamon
			kimchi cumin winter cherry arugula salad Caribbean red habanero broccoli peanut butter
			crunch.
		</p>
		<p>
			Hemp seeds apple vinaigrette dark and stormy habanero golden coriander peppermint asian
			pear frosted gingerbread bites Southern Italian almond milk chai latte mint golden
			cayenne pepper. Salted dark chocolate bruschetta figs green tea lime mediterranean
			second course dessert sesame soba noodles overflowing strawberry spinach salad.
		</p>
		<p>
			Hearty refreshing cucumber splash cherry chickpea crust pizza banana black bean wraps
			red amazon pepper banana bread arugula salad edamame avocado dressing drizzle veggie
			burgers heat green pepper soy milk lingonberry shaved almonds raspberry fizz lemongrass
			matcha salty. Portobello mushrooms coconut sugar sriracha pecans spring cool cucumbers
			lemon lime minty chia seeds lemon blueberry chia seed jam Italian pepperoncini Malaysian
			sweet potato sleepy morning tea balsamic vinaigrette street style Thai basil tacos seeds
			chai tea crispy ultimate cool off cozy butternut smoked tofu blueberries pasta bananas.
		</p>
	</cdx-dialog>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue';
import { CdxButton, CdxDialog, DialogAction } from '@wikimedia/codex';
export default defineComponent( {
	name: 'DialogMaxContent',
	components: {
		CdxButton,
		CdxDialog
	},
	setup() {
		const open = ref( false );
		const defaultAction: DialogAction = {
			label: 'Close'
		};
		return {
			open,
			defaultAction
		};
	}
} );
</script>

With stacked actions

When action button text is long, use the stackedActions prop to stack the action buttons vertically.

With optional Footer Text

The footer-text slot can accept plain text, links, and basic formatting markup; do not use it to provide images or block-level elements. All content provided is wrapped inside of a <p> tag. Use this slot for situations like showing a disclaimer, linking to help or legal documentation, etc. The footer-text content will appear above the dialog actions.

With custom Header and Footer

By default, the Dialog displays a header with an optional title, subtitle, and close button, and a footer with optional buttons and footer text.

The entire content of the header and footer can be replaced with user-provided markup (by using the #header and #footer slots, respectively). This allows for the creation of one-off custom dialogs as well as variant Dialog components that wrap the base Dialog with some additional content and styling.

Reusable custom Dialog example

The example above demonstrates a unique Dialog instance, suitable for a one-off dialog. For a re-usable custom dialog, consider using a wrapper component.

A wrapper component could pre-apply certain customizations (a consistent custom header or footer, for example) while still accepting <slot> content from the user that gets forwarded to the Dialog's own slots.

An example of how to write such a component can be found below. This example relies on Codex's useModelWrapper composable to pass a v-model binding from the parent context down to the inner Dialog component.

Usage of the custom component would look like this:

vue

<wrapped-dialog
  title="Custom dialog header"
  v-model:open="wrappedDialogState"
>  
	Custom dialog content.  
</wrapped-dialog>

vue

<!-- WrappedDialog.vue -->
<template>
	<cdx-dialog
		v-model:open="wrappedModel"
		:title="title"
		class="wrapped-dialog"
	>
		<template #header>
			<div>
				<h2>{{ title }}</h2>
			</div>
			<div>
				<cdx-button
					weight="quiet"
					aria-label="close"
					@click="wrappedModel = false"
				>
					Skip
				</cdx-button>
			</div>
		</template>

		<slot />

		<template #footer>
			<cdx-checkbox v-model="checkboxValue">
				Don't show again
			</cdx-checkbox>

			<!-- This button is wired to emit a custom "next" event instead of
			simply closing the dialog -->
			<cdx-button
				weight="primary"
				action="progressive"
				aria-label="Next"
				@click="$emit( 'next' )"
			>
				<cdx-icon :icon="cdxIconNext" />
			</cdx-button>
		</template>
	</cdx-dialog>
</template>

<script lang="ts">
import { defineComponent, ref, toRef } from 'vue';
import { CdxButton, CdxCheckbox, CdxDialog, CdxIcon, useModelWrapper } from '@wikimedia/codex';
import { cdxIconNext } from '@wikimedia/codex-icons';

export default defineComponent( {
	name: 'WrappedDialog',

	components: {
		CdxButton,
		CdxCheckbox,
		CdxDialog,
		CdxIcon
	},

	props: {
		open: {
			type: Boolean,
			default: false
		},

		title: {
			type: String,
			default: 'Title'
		}
	},

	emits: [
		'update:open',
		'next'
	],

	setup( props, { emit } ) {
		const checkboxValue = ref( false );
		const wrappedModel = useModelWrapper( toRef( props, 'open' ), emit, 'update:open' );

		return {
			checkboxValue,
			cdxIconNext,
			wrappedModel
		};
	}
} );
</script>

<style lang="less">
@import ( reference ) '@wikimedia/codex-design-tokens/theme-wikimedia-ui.less';

.wrapped-dialog {
	header {
		background-color: @background-color-progressive-subtle;
		display: flex;
		align-items: flex-start;
		justify-content: space-between;
		// Custom bigger height.
		height: @size-800;
		padding: @spacing-100 @spacing-100 0 @spacing-100;

		h2 {
			margin: 0;
			padding: 0;
			font-size: @font-size-large;
		}
	}

	footer {
		display: flex;
		align-items: baseline;
		justify-content: space-between;
		border-top: @border-style-base @border-width-base @border-color-subtle;
		padding: @spacing-75 @spacing-100 @spacing-50 @spacing-100;
	}
}
</style>

Usage

Props

Prop name	Description	Type	Default
`open`	Whether the dialog is visible. Should be provided via a v-model:open binding in the parent scope.	`boolean`	`false`
`title`^(required)	Title for the dialog header. Used for ARIA purposes even if no visible header element is displayed.	`string`
`subtitle`	Optional subtitle for the dialog.	`string`	`null`
`hideTitle`	Whether the dialog header should hide the title & subtitle	`boolean`	`false`
`closeButtonLabel`	Label for the icon-only close button in the header. Including this prop adds the close button.	`string`	`''`
`primaryAction`	Primary user action. This will display a primary button with the specified action (progressive or destructive).	`PrimaryDialogAction`	`null`
`defaultAction`	Default user action. This will display a normal button.	`DialogAction`	`null`
`stackedActions`	Whether action buttons should be vertically stacked and 100% width.	`boolean`	`false`

Events

Event name	Properties	Description
`primary`		When the primary action button is clicked.
`default`		When the default action button is clicked.
`update:open`	newValue `boolean` - The new open/close state (true for open, false for closed)	When the open/close state changes, e.g. when the close button is clicked.

Slots

Name	Description	Bindings
header	Customizable Dialog header
default	Dialog content
footer	Customizable Dialog footer
footer-text	Optional footer text

Dialog ​

Demos ​

Configurable Dialog ​

Basic example ​

With expandable menus ​

With overflowing content ​

With stacked actions ​

With optional Footer Text ​

With custom Header and Footer ​

Reusable custom Dialog example ​

Usage ​

Props ​

Events ​

Slots ​