Skip to content

Dialog

Dialogs are elements that are overlaid on a web page or app in order to present necessary information and tasks. Dialogs are also sometimes referred to as modals or overlays.

Guidelines

Using dialogs

Dialogs facilitate communication between the system and user. They perform best when used for urgent decisions or as a workflow within a bigger task, as they don’t require loading a new page and keep actions in context.

Dialogs can be intentionally disruptive, since the user needs to interact with or close the dialog before moving on. For this reason, they should be used sparingly and only when necessary (more information below).

Example of a Codex Dialog with a title, paragraph, two action buttons, and a close button.

When to use:

  • When the user needs to make a decision or provide input to the system before continuing with the task at hand.
  • When additional information needs to be displayed and separated from the page content.
  • When the user needs to provide additional confirmation before taking an action.

When not to use:

  • When the information can be displayed inline within the main interface.
  • When the information is not important enough to interrupt the user's flow.
  • When the content within the dialog is so long that it requires scrolling. In this case, split the dialog content into different steps or provide it on a dedicated page.
  • When dealing with a lengthy form comprising numerous form fields and actions. In this case it's more appropriate to create the form on a separate page.

Specifications

Specification of Dialog.

A dialog contains:

  1. Title
    All dialogs should include a title. This should be a short, one-line overview of the purpose of the dialog.
  2. Subtitle (optional)
    A subtitle can be used to provide additional information about the dialog.
  3. Body
    Any type of content or components can be included within the dialog’s body.
  4. Footer text (optional)
    Further text can be included above the action buttons, in order to provide additional information (e.g. terms and conditions to read before publishing).
  5. Permanent action (optional)
    A permanent action can be included (e.g. “Don’t show again”). Main action: A primary button (either progressive or destructive) is used to indicate the main action.
  6. Secondary action (optional)
    A normal neutral button can be used to indicate a secondary action (e.g. “Cancel”).
  7. Close button (optional)
    A quiet, icon-only button may be used to close the dialog. It can also be replaced with a text button in some cases.

Behind every dialog, there is an overlay that displays the color White (#fff) at 65% opacity. This is to provide continued context while the user focuses on the dialog.

A white overlay separating a dialog from a Wikipedia page.

If the action buttons’ text is too long, the main action button may be stacked above the secondary action.

A dialog with stacked buttons due to their lengthy text.

Scrolling

If needed, scrolling is allowed in dialogs, but should be used sparingly. While scrolling, top and bottom dividers appear and both the top and bottom sections become fixed as content scrolls underneath them.

A dialog is being scrolled with fixed head and footer sections.

Closing

A dialog can be dismissed by:

  • The close button (X)
  • A dismissive action like “Cancel“
  • Tapping or clicking anywhere outside of the dialog on the background
  • Pressing the key ‘esc’

A representation of how dialogs can be closed.

Maximum width and height

All dialogs are vertically and horizontally centered on the canvas. We aim to keep dialogs at a fixed width of 512dp on desktop, while allowing them to use 90% of the width on mobile web. This makes dialogs the focus of the screen.

A desktop and mobile mockup of a Wikipedia page with a dialog displayed on the center of the page.

Refer to the Dialog component in Codex Figma.

Interaction states

Buttons may be disabled until a required action is completed.

A dialog with a disabled main button.

Content

Simple dialogs are for confirmations and information that the user needs in order to continue. It is easier for users to move through the flow when they know what to do from the title and CTAs.

A screenshot of an interface dialog conveying an example of short, concise titles and text.

Do:
  • Write short titles and simple CTAs to work together. Concise & Clear

A screenshot of an interface dialog conveying an example of unnecessarily long text and an action which does not relate to the purpose of the dialog.

Don't:
  • Give too much information or too many options. Concise & Clear

Demos

Configurable Dialog

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.

With stacked actions

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

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.

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 usage

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").

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.

Dialog and <teleport>

Dialogs rely on Vue's built-in <teleport> feature, and a "target" prop can be supplied which will be passed to the teleport's to prop. This prop is optional and defaults to the <body> element on the page (although if Dialog is being used with SSR, a dedicated target should be provided).

An alternative default target can be set using Vue's provide/inject feature, with provide( 'CdxTeleportTarget', '#my-teleport-target' ). This provided target will be used if the "target" prop is not set.

Finally, Dialog teleportation behavior can be disabled by setting renderInPlace: true.

The examples on this page are all wrapped with Vitepress's built-in <client-only> component, since the Codex documentation site (built with Vitepress) uses SSR. Other SSRed applications will need to do something similar (only rendering Dialog after the mounted hook has been fired, etc.).

Use of the Dialog component in features which don't rely on SSR (which includes all MediaWiki usage for now) can dispense with this.

Props

Prop nameDescriptionTypeDefault
openWhether the dialog is visible. Should be provided via a v-model:open binding in the parent scope.booleanfalse
title(required)Title for the dialog header. Used for ARIA purposes even if no visible header element is displayed.string
subtitleOptional subtitle for the dialog.stringnull
hideTitleWhether the dialog header should hide the title & subtitlebooleanfalse
closeButtonLabelLabel for the icon-only close button in the header.

Including this prop adds the close button.
string''
primaryActionPrimary user action. This will display a primary button with the specified action (progressive or destructive).PrimaryDialogActionnull
defaultActionDefault user action. This will display a normal button.DialogActionnull
stackedActionsWhether action buttons should be vertically stacked and 100% width.booleanfalse
targetSelector or DOM element identifying the container the dialog should be rendered in. The dialog will be <teleport>ed to this element. An ID selector is recommended, e.g. #foo-bar, but providing an actual element is also supported.

If this prop is not set, and the parent or one of its ancestors provides a teleport target using provide( 'CdxTeleportTarget', '#foo-bar' ), the provided target will be used. If there is no provided target, the dialog will be teleported to the end of the <body> element.
string|HTMLElement|nullnull
renderInPlaceWhether to disable the use of teleport and render the Dialog in its original location in the document. If this is true, the target prop is ignored.booleanfalse

Events

Event namePropertiesDescription
primaryWhen the primary action button is clicked.
defaultWhen the default action button is clicked.
update:opennewValue 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

NameDescriptionBindings
headerCustomizable Dialog header
defaultDialog content
footerCustomizable Dialog footer
footer-textOptional footer text