The DialogPrimitive contains the building blocks used to construct dialog-based components and consists of:

• DialogPrimitive::Wrapper is the structure that contains and arranges all other dialog primitives.
• DialogPrimitive::Header contains the title, dismiss button, and optionally a visually supportive icon and tagline.
• DialogPrimitive::Description contains optional descriptive information about the dialog.
• DialogPrimitive::Body is a generic container that houses the main content or message of the dialog.
• DialogPrimitive::Footer contains buttons to act on the content in the body container or link to additional resources.

Usage

The DialogPrimitive sub-components are not intended to be used independently of each other or in isolation. If you are looking to create your own dialog-based component, use the DialogPrimitive::Wrapper as your foundation.

A common example of this is a non-modal dialog such as a SplitWindow or Panel, which allows the user to interact with both the main page content and the content within the dialog.

Use within HDS components

Examples of how to use the DialogPrimitive components can be found in the HDS Modal and Flyout components which are composed using the DialogPrimitive. They are both types of dialogs, but have different use cases depending on the context and type of information they convey.

What is a “dialog”

The term “dialog” has somewhat of a loaded meaning and, depending on the context, can be either an ambiguous high-level term or have a specific semantic meaning. For example:

• Broadly, the term dialog can refer to the interaction between a user and an application or machine that encourages a bidirectional exchange of information between the two.
• Specifically, a dialog can refer to a semantic <dialog> element in HTML. This element can be further broken down into modal and non-modal dialogs, more details of which can be found in the MDN documentation.

The DialogPrimitive Wrapper is built on the HTML <dialog> element, and therefore supports the same JavaScript API.

How to use this component

The DialogPrimitive serves as the foundation for dialog derived components like the Modal and Flyout. Unlike other HDS primitives, we recommended using DialogPrimitive components directly when you need to create a dialog with a custom layout. This is particularly useful for constructing non-modal dialogs that integrate into a page layout, rather than floating above it.

Basic dialog using DialogPrimitive components

<Hds::DialogPrimitive::Wrapper>
  <:header>
    <Hds::DialogPrimitive::Header
      @icon="info"
      @tagline="Tagline"
    >
      Title
    </Hds::DialogPrimitive::Header>
    <Hds::DialogPrimitive::Description>Description</Hds::DialogPrimitive::Description>
  </:header>
  <:body>
    <Hds::DialogPrimitive::Body>
      <p class="hds-typography-body-300 hds-foreground-primary">Lorem ipsum dolor sit amet consectetur
        adipisicing elit. Libero culpa expedita assumenda at nisi minus unde fuga iure suscipit aut qui, odit
        natus eum voluptates ut molestiae! Perferendis, impedit qui? Lorem ipsum dolor sit amet?</p>
    </Hds::DialogPrimitive::Body>
  </:body>
  <:footer>
    <Hds::DialogPrimitive::Footer>
      <Hds::ButtonSet>
        <Hds::Button type="submit" @text="Primary" />
        <Hds::Button type="button" @text="Secondary" @color="secondary" />
      </Hds::ButtonSet>
    </Hds::DialogPrimitive::Footer>
  </:footer>
</Hds::DialogPrimitive::Wrapper>

Header titleTag

The @titleTag argument changes the HTML element that wraps the DialogPrimitive::Header tagline and "title" content. When organizing the content on a webpage, the heading levels should reflect the structure of the page. For example, if the DialogPrimitive is used as a Split Window, the value should be "h2".

<div class="doc-dialog-primitive-grid-layout">
  <div class="doc-dialog-primitive-flex-layout">
    <Hds::Text::Display @tag="h1" @size="500">Page title</Hds::Text::Display>
    <Doc::Placeholder @text="Main content" @height="100%" @width="100%" @background="#eee" />
  </div>
  <Hds::DialogPrimitive::Wrapper class="doc-dialog-primitive-with-border">
    <:header>
      <Hds::DialogPrimitive::Header
        @icon="info"
        @tagline="Tagline"
        @titleTag="h2"
      >
        Split Window
      </Hds::DialogPrimitive::Header>
    </:header>
    <:body>
      <Hds::DialogPrimitive::Body>
       <Doc::Placeholder @text="Split Window content" @height="10rem" @width="100%" @background="#eee" />
      </Hds::DialogPrimitive::Body>
    </:body>
    <:footer>
      <Hds::DialogPrimitive::Footer>
        <Hds::ButtonSet>
          <Hds::Button type="submit" @text="Primary" />
          <Hds::Button type="button" @text="Secondary" @color="secondary" />
        </Hds::ButtonSet>
      </Hds::DialogPrimitive::Footer>
    </:footer>
  </Hds::DialogPrimitive::Wrapper>
</div>

Component API

A custom dialog can be implemented by composing the Wrapper, Header, Description, Body, Footer (and potentially Overlay) DialogPrimitive sub-components.

DialogPrimitive::Wrapper

This is the component used to provide the overall layout to the dialog.

DialogPrimitive::Header

A sub-component used to provide the header content.

DialogPrimitive::Description

A sub-component used to provide an extra description to the header.

DialogPrimitive::Body

A sub-component used to contain the main content of the dialog. When the yielded content exceeds the available space, a scrollbar is introduced to the container.

DialogPrimitive::Footer

A sub-component used to provide the footer’s content. We recommend using it exclusively for actions using the ButtonSet component. If a tertiary action is included, it will always be aligned at the end of the row.

The component also offers an onDismiss argument, yielded as F.close, but it’s only used internally in the Modal and Flyout components.

DialogPrimitive::Overlay

An overlay element that can be used to display a backdrop behind a modal dialog.

Consumers will need to take care of combining the DialogPrimitive::Overlay with the DialogPrimitive::Wrapper (with header, body, and footer content) by wrapping them in a parent container and implementing the desired layout.

Anatomy

Conformance rating

DialogPrimitive components are primarily containers which can be combined together to build a custom dialog and are not conformant on their own. Consumers are responsible for implementing the primitives in a way that results in a conformant experience for the user.

Applicable WCAG Success Criteria

This section is for reference only. This component intends to conform to the following WCAG Success Criteria:

Support

If any accessibility issues have been found within this component, let us know by submitting an issue.

4.11.1

Updated

Fixed issue with box-sizing inheritance due to a all: unset CSS rule

4.10.0

Updated

DialogPrimitive::Header

• Added the @titleTag argument

4.7.0

Added

Added a set of utility "dialog" sub-components to act as primitives for Modal and Flyout (and to be used as standalone subcomponents if needed):

• DialogPrimitive::Wrapper
• DialogPrimitive::Header
• DialogPrimitive::Description
• DialogPrimitive::Body
• DialogPrimitive::Footer