• Components/

Modal

CdrModal

Display additional page content in an overlay

# Overview

View on GitHub
View on CodeSandbox

# Accessibility

Ensure that usage of this component complies with accessibility guidelines:

  • 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

This component has compliance with WCAG guidelines by:

  • Selecting the appropriate attributes and aria roles:
    • For modal without title: aria-label
    • For short modal: aria-describedby
    • For longer modal: assign role="document" to the modal content
  • 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
  • Two width options are available: 600px (default) and 800px (large)
  • 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.

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.

# Events

closed

name

$emit event fired when closing the modal.

# Usage

<cdr-modal
  label="Add to Cart"
  :opened="opened"
  @closed="closed"
  aria-described-by="description"
>
  <template slot="title">
    <cdr-text
        tag="h1"
        modifier="heading-600"
      >Add to Cart
    </cdr-text>
  </template>
  <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec sit amet dictum ipsum.</p>
</cdr-modal>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

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 slot="title">
  <cdr-text
    tag="h1"
    modifier="heading-600"
  >Add to Cart
  </cdr-text>
</template>
1
2
3
4
5
6
7

# 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.

# Accessibility

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

<template>
  <cdr-button
    aria-haspopup="dialog"
  >Launch modal</cdr-button>
</template>
1
2
3
4
5

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-described-by="description"
  >
    ...
  </cdr-modal>
</keep-alive>
1
2
3
4
5
6
7
8
9
10
11