Skip to main content

Dialog

Dialogs open on top of the main window and require the user to interact with it. In most cases, dialogs block interactions with the web page until being explicitly dismissed, and often request some kind of action from the user.

Example

Different styles of dialog on a default theme

Best practices

Use a dialog to contain important information that the user must read and acknowledge before proceeding. Examples include:

  • When the user’s security might be compromised.
  • When the user is about to permanently alter or delete a valuable asset.
  • To confirm a purchase.

Do

  • The primary button within a dialog should be the non-destructive button. For example, when saving work, and given buttons for "Save" and "Cancel", the "Save" button should be the primary button.
  • The primary button ("OK") should go on the right. A secondary command ("Cancel") goes on the left.

Don’t

  • Don’t overuse dialogs. To some extent they can be perceived as interrupting workflow and too many can be a bad user experience.

Also known as

Lightbox
Popup menu
Modal

Related

Button
Heading
Paragraph
Progress

Accessibility

  • When a Dialog is shown, all other regions of content must be hidden from screen readers. By default, the Dialog will hide content in the first data-grid="container" element in the page. If you have content outside of that element, you can identify that region to be hidden by adding the data-js-describedby="dialog" attribute and value to that content container.

Options

  • The dialog is triggered by an element from the data-js-dialog-show="id" data attribute. The id of the dialog must match the data attribute.
  • The default dialog supports single or multiple buttons with text content and no other actionable items.
  • Flow: Add the class name f-flow to allow for actionable items and other content (such as images or video) to be within the dialog.
  • Lightbox: Add a class name f-lightbox to have the dialog appear as a light box. To be used with video or images.

Development

  • JavaScript: Scripting documentation defines how to handle this component through JavaScript.
  • Schema definition: The dialog schema defines the acceptable configurations, requirements, and options for each component.

Code and preview

Default Dialog (triggered by element with data-js-dialog-show="default-dialog-single-preview")

<div class="c-dialog" id="default-dialog-single-preview" aria-hidden="true">
    <div role="presentation" tabindex="-1"></div>
    <div role="dialog" aria-label="Default" tabindex="-1">
        <div role="document">
            <h2>Dialog title</h2>
            <div>
                <p class="c-paragraph">Paragraph lorem ipsum sit amet, consectetur adipiscing elit. Duis ut commodo ante. Integer mattis a ligula quis ullamcorper. Nam placerat quam sed nulla tristique mattis.</p>
            </div>
            <div class="c-group">
                <button class="c-button" type="submit" data-js-dialog-hide aria-label="Close dialog">Close</button>
            </div>
        </div>
    </div>
</div>

Default Dialog with progress (triggered by element with data-js-dialog-show="defaultDialogProgress")

<div class="c-dialog" id="defaultDialogProgress" aria-hidden="true">
    <div role="presentation" tabindex="-1"></div>
    <div role="dialog" aria-label="Default progress" tabindex="-1">
        <div class="c-progress f-indeterminate-regional" role="progressbar" aria-valuetext="Loading..." tabindex="0" aria-label="Indeterminate regional progress bar">
            <span></span>
            <span></span>
            <span></span>
            <span></span>
            <span></span>
        </div>
        <div role="document">
            <h2>Dialog title</h2>
            <div>
                <p class="c-paragraph">Lorem ipsum dolor sit amet, ei zril soleat ius. Ius at legere alienum argumentum. Qui et nobis primis incorrupte, vix id dicat malorum. Te detracto efficiantur ius, an erant viris theophrastus ius, patrioque scriptorem an nec. Sed prompta
                    reprimique cu. Soluta constituam mei at.</p>
            </div>
            <div class="c-group">
                <button class="c-button" type="submit" data-js-dialog-hide aria-label="Close dialog">Close</button>
            </div>
        </div>
    </div>
</div>

Dialog with flow option (triggered by element with data-js-dialog-show="flow-dialog-single-light-theme-preview")

<div class="c-dialog f-flow" id="flow-dialog-single-light-theme-preview" aria-hidden="true">
    <div role="presentation" tabindex="-1"></div>
    <div role="dialog" aria-label="Flow" tabindex="-1">
        <button class="c-glyph glyph-cancel" data-js-dialog-hide aria-label="Close dialog" tabindex="0"></button>
        <div role="document">
            <h2>Dialog title</h2>
            <div>
                <p class="c-paragraph">Paragraph lorem ipsum sit amet, consectetur adipiscing elit. Duis ut commodo ante. Integer mattis a ligula quis ullamcorper. Nam placerat quam sed nulla tristique mattis.</p>
            </div>
            <div class="c-group">
                <button class="c-button" type="submit" data-js-dialog-hide aria-label="Close dialog">Close</button>
            </div>
        </div>
    </div>
</div>

Flow with scroll option (triggered by element with data-js-dialog-show="flow-dialog-scroll")

<div class="c-dialog f-flow" id="flow-dialog-scroll" aria-hidden="true">
    <div role="presentation" tabindex="-1"></div>
    <div role="dialog" aria-label="Flow scroll" tabindex="-1">
        <button class="c-glyph glyph-cancel" data-js-dialog-hide aria-label="Close dialog" tabindex="0"></button>
        <div role="document">
            <div>
                <h2>Dialog title</h2>
            </div>
            <div class="f-dialog-scroll">
                <p class="c-paragraph">Lorem ipsum dolor sit amet, ei zril soleat ius. Ius at legere alienum argumentum. Qui et nobis primis incorrupte, vix id dicat malorum. Te detracto efficiantur ius, an erant viris theophrastus ius, patrioque scriptorem an nec. Sed prompta
                    reprimique cu. Soluta constituam mei at. Sed debet abhorreant id, ullamcorper reprehendunt sea et. Aeterno utroque eligendi at mel. Pri no meis congue omnesque, cetero timeam ad eam, id eum eros offendit. Esse omnium blandit ad mea,
                    vix iudicabit assentior ei. Duo et vero petentium, ei mei tale sapientem, verterem accusamus ius eu. Oblique numquam noluisse eos ea, vel malorum sapientem ea, eum ne unum aperiam postulant. Ius in vidisse tacimates, admodum vituperata
                    usu ut. An eam dictas recusabo, tota adipisci honestatis vix te. Ius ex inani vidisse mandamus, quo te dicant tractatos incorrupte. Per no justo noluisse. Cu cetero platonem salutandi sit, ei vim clita invenire quaestio, ei vis quas
                    minim voluptatibus. Mei senserit qualisque concludaturque no, est fabulas maiestatis ei. Magna veritus qui ut, possim inciderint id mel. Vim impetus adversarium ei, vix dictas fastidii te. Congue doctus nominati eu vis, has in primis
                    eleifend convenire, velit summo ei mel. At quo nulla feugiat. Eam omnesque disputando no, sint fugit vel te. At facete scriptorem eos, liber eirmod eu vel. Qui id iudico graeco veritus, essent disputationi et sea. At est lorem viris,
                    ea prima mundi partiendo quo. Semper civibus assueverit ut nam, nam tamquam fuisset id. No eum mutat nulla facete. Vel clita molestie forensibus ea, eam nostro dolores reprehendunt in, usu eros tota elitr ad. Latine perfecto an sea,
                    prodesset concludaturque nec id. Eruditi oporteat abhorreant at eam, at has legimus dolores. Discere imperdiet quaerendum eam ex, te legere audire vulputate nam, ad disputationi voluptatibus eos. Percipitur eloquentiam ad vix. Semper
                    civibus assueverit ut nam, nam tamquam fuisset id. No eum mutat nulla facete. Vel clita molestie forensibus ea, eam nostro dolores reprehendunt in, usu eros tota elitr ad. Latine perfecto an sea, prodesset concludaturque nec id. Eruditi
                    oporteat abhorreant at eam, at has legimus dolores. Discere imperdiet quaerendum eam ex, te legere audire vulputate nam, ad disputationi voluptatibus eos. Percipitur eloquentiam ad vix.</p>
            </div>
            <div class="c-group">
                <button class="c-button" type="submit" data-js-dialog-hide aria-label="Close dialog">Close</button>
                <button class="c-button" type="button">Button</button>
            </div>
        </div>
    </div>
</div>

Dialog with flow and without close glyph

<div class="c-dialog f-flow" id="flow-dialog-single-light-theme-no-close-preview" aria-hidden="true">
    <div role="presentation" tabindex="-1"></div>
    <div role="dialog" aria-label="Flow" tabindex="-1">
        <div role="document">
            <h2>Dialog title</h2>
            <div>
                <p class="c-paragraph">Paragraph lorem ipsum sit amet, consectetur adipiscing elit. Duis ut commodo ante. Integer mattis a ligula quis ullamcorper. Nam placerat quam sed nulla tristique mattis.</p>
            </div>
            <div class="c-group">
                <button class="c-button" type="submit" data-js-dialog-hide aria-label="Close dialog">Close</button>
            </div>
        </div>
    </div>
</div>

Dialog with lightbox option (triggered by element with data-js-dialog-show="default-lightbox-preview")

<div class="c-dialog f-lightbox" id="default-lightbox-preview" aria-hidden="true">
    <div role="presentation" tabindex="-1"></div>
    <button class="c-glyph glyph-cancel" data-js-dialog-hide aria-label="Close dialog" tabindex="0"></button>
    <div role="dialog" aria-label="Lightbox" tabindex="-1">
        <div role="document">
            <img alt="Placeholder" src="http://placehold.it/550x250">
        </div>
    </div>
</div>