• Click Me

Overview

Primary Secondary

View on GitHub

View on CodeSandbox

Multiple Modals On One Page

When rendering multiple modals on a single page you can reduce your markup size by using a single CdrModal instance to launch all of the modals.

Primary Secondary

View on GitHub

View on CodeSandbox

Using Modals as alert dialogs

In the above example the cdr-modal role property of the "Terms and Conditions" modal has been changed to alertdialog. This role will notify users of critical information requiring their immediate attention.

  <cdr-modal role="alertdialog" aria-describedby="description" label="modal title">
    <div id="description">
      modal content description
    </div>
  </cdr-modal>

Generally they have at least a Confirmation and close button but can have additional interactive controls as needed. Like a traditional modal dialog, alert dialogs move and capture the users focus to the blocking overlay window. By default focus will be placed on the modal window however for alert dialogs you should alter this to be placed on the most appropriate interactive control

The alertdialog role should only be used when an alert occurs. Additionally, an alert dialog may only be used for alert messages which have associated interactive controls. Review alert for requirements on an alert which only contains static content and has no interactive controls.

Accessibility

Ensure that usage of this component complies with accessibility guidelines:

• If your modal is launched by a button, add aria-haspopup="dialog" to the button element:

<cdr-button
  aria-haspopup="dialog"
>Launch modal</cdr-button>

• Set the aria-describedby prop to point to an element that describes what the modal does:

  <cdr-modal aria-describedby="description" label="modal title">
    <div id="description">
      modal content description
    </div>
  </cdr-modal>

This component complies with WCAG guidelines by:

• Uses the label prop to set the aria-label
• Assigns role="document" to the modal content
• All text content within the modal is read by screen readers, including the Close button text
• Only the content in the modal is read by the screen reader. Content outside modal is not read when the modal is in focus
• Modal can be closed using the keyboard (ESC key), Close button, or by clicking outside of modal
• Using the aria-hidden and tabindex="-1" on focusable items for all content outside of the modal

Guidelines

Use When

• Displaying important information users need to respond to
• Displaying non-essential content related to the underlying page that exceeds 560 characters

Don't Use When

• Displaying limited additional page content
• Providing status feedback or messages

The Basics

• Use modals sparingly. Modals are disruptive and their sudden appearance forces users to stop their current task and focus on the modal content
• Headlines should not exceed 68 characters
• Modal centers within the page
• Keep modal titles succinct and informative

Behavior

• If two buttons are needed, place the primary button on the left and the secondary button on the right. Stack buttons at XS
• Content behind modal does not scroll and cannot be interacted with in any way
• Gradient is added at bottom to signify further scrollable content
• Modal is dismissed by:
  • Clicking the Close button
  • Interacting with the overlay background
  • Pressing the escape key (ESC)
• Modal opens one at a time and are never displayed in groups

API

Props

opened

name

Boolean

type

N/A

default

Toggles the state of the modal. Required.

label

name

string

type

N/A

default

Text used to generate the `aria-label` attribute as well as the modal title text, if `labelSlot` is empty. Required.

showTitle

name

boolean

type

true

default

Toggles the modal title text, which comes from `label` or `labelSlot`.

ariaDescribedby

name

string

type

'medium'

default

Text for the `aria-describedby` attribute.

id

name

string

type

null

default

Unique id for modal.

role

name

string

type

dialog

default

Overrides the `role` attribute on the modal content element. Possible values: { 'dialog' | 'alertdialog' }

overlayClass

name

string

type

N/A

default

Adds a custom class to the `cdr-modal__overlay` div.

wrapperClass

name

string

type

N/A

default

Add a custom class to the `cdr-modal__outerWrap` div.

contentClass

name

string

type

N/A

default

Add a custom class to the `cdr-modal__innerWrap` div.

animationDuration

name

number

type

300

default

Sets animation duration for when the modal is closed.

Slots

Find more information about using Slots in the article Getting Started as a Developer.

default

name

Slot for CdrModal content.

title

name

Slot for CdrModal title.

modal

name

Slot to override the entire CdrModal content.

Events

closed

name

$emit event fired when closing the modal.

Usage

Modal Title

If the title slot is left empty, the label prop will be rendered as the title. The title can be hidden altogether by setting showTitle to false.

When using the label slot, add CdrText to use the appropriate header styles.

<template #title>
  <cdr-text
    tag="h1"
    class="custom-text-class"
  >Add to Cart
  </cdr-text>
</template>

Size

The modal has a default width of 640px which converts to a fullscreen view at xs screen sizes.

Scroll Behavior

The modal content area will scroll vertically if there's enough content. The modal title does not scroll; it stays affixed to the top of the modal.

Keep Alive

Do not use v-if with CdrModal unless the component is wrapped with keep-alive. CdrModal handles showing and hiding itself when toggling, so v-if should be unneeded in most cases.

<keep-alive>
  <cdr-modal
    v-if="opened"
    :opened="opened"
    label="Add to Cart"
    @closed="closed"
    aria-describedby="description"
  >
    ...
  </cdr-modal>
</keep-alive>