In progress

Dialog

Dialog is a content structure component that provides a consistent layout for a title, body content, and actions, and it is designed to be used inside Modal or BottomSheet components; it does not provide overlay, backdrop, or focus management on its own.

• Figma
• Storybook
• Edit this page
• Create a new issue

Dialog Title

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam aliquid cupiditate ea earum nemo pariatur, repellendus. Accusamus accusantium adipisci animi corporis doloremque, nemo, nobis obcaecati officiis perferendis provident, rem tempore.

Asperiores ea eum exercitationem nesciunt nihil, possimus rerum sunt vitae? Accusamus aut fugiat incidunt itaque laudantium, natus possimus reiciendis suscipit unde vel? Dicta eius excepturi fugit necessitatibus non, odio praesentium.

A architecto at beatae commodi cupiditate delectus ea eligendi, eveniet excepturi explicabo fuga incidunt laborum maiores minima minus necessitatibus nostrum odio possimus quae quam quis sit vel vero voluptatem voluptatum?

Ab autem inventore quidem quisquam sequi vitae voluptate voluptatibus? A minus odit placeat sit! At consectetur, culpa ducimus error facilis illo impedit, maxime officiis quae quidem recusandae totam voluptates voluptatum.

Amet debitis distinctio esse labore officiis optio sunt voluptatem. Aliquid corporis distinctio dolor dolore doloremque, facilis fuga harum libero maiores pariatur recusandae rem repellat sequi voluptas voluptate. Ex, iure ullam.

Ad consequatur dicta facere inventore ipsam libero soluta suscipit tenetur velit. A adipisci consectetur dignissimos fuga incidunt minima nihil nobis officia, possimus quam quibusdam quidem quos reiciendis similique sunt, voluptatem!

Aperiam consequatur deserunt illum nihil optio, possimus quia quibusdam quisquam? A blanditiis debitis eius ex illum incidunt, ipsa ipsum nemo, nisi numquam obcaecati omnis perferendis quaerat repellat saepe sint voluptas?

Asperiores assumenda at consectetur consequuntur cumque deleniti dolores ducimus eius et expedita hic, id magni maiores molestias placeat praesentium, quidem sequi sunt tenetur ut! Harum illo maiores quas quia repellendus.

A ab architecto at beatae blanditiis deleniti dolores dolorum esse expedita, ipsa libero molestiae, mollitia nobis odit officiis, optio perferendis reiciendis repellat sapiente similique tempora unde voluptatibus voluptatum! Ex, quaerat.

Accusantium, adipisci, aliquam aspernatur atque dignissimos dolor earum esse est ex expedita hic illo ipsam laboriosam laborum laudantium magni mollitia neque obcaecati odio officia qui ratione repudiandae, saepe totam voluptate!

Animi consequuntur fuga fugiat, minima optio quas totam. Aut consectetur, dicta eius ex facilis minima non obcaecati placeat quisquam reiciendis tenetur unde vero vitae! Ad corporis culpa facere officia voluptatibus?

Cumque dolorum est facilis id impedit ipsa ipsam iure nulla pariatur perspiciatis porro ratione reprehenderit sapiente sequi sint sit totam ut vel, vero voluptate. Ex optio porro provident repudiandae totam.

A aliquam blanditiis ea iusto magnam maxime qui, quia quidem repudiandae similique sit suscipit, tempore temporibus? Alias aliquam aut beatae consectetur dolore error iure labore maiores, nam nemo nobis voluptas!

Animi est, facere facilis itaque nihil quam quos! Amet ea ex illum nemo optio recusandae repellendus. Cupiditate ipsum iure laborum nam placeat provident voluptatum? Dolores nam officia quo rem tenetur!

Animi asperiores aspernatur consequuntur cupiditate deleniti dignissimos dolor doloribus error est fugit, itaque laborum minus molestiae molestias natus nobis nostrum officiis omnis placeat quibusdam recusandae reiciendis rerum sed ullam veritatis.

Adipisci alias architecto assumenda debitis deserunt dignissimos ipsum itaque maiores qui quis. Aperiam at et eum, exercitationem id ipsa minus modi non odit, placeat provident quisquam recusandae sit veritatis voluptas!

Aliquam architecto asperiores assumenda at autem distinctio ducimus exercitationem expedita facere facilis inventore ipsum laboriosam minima modi neque nesciunt nisi quibusdam repellendus, sequi temporibus vero vitae voluptate voluptatem? Assumenda, beatae!

Amet consequuntur, dignissimos dolore ea impedit incidunt inventore libero maiores nihil obcaecati quibusdam recusandae rem tempora vel veniam? Adipisci dolorum enim eum in inventore itaque mollitia pariatur repellendus tempora, totam.

Aliquid autem, cum dicta doloribus error fugit ipsum iusto laborum modi provident quae quam quas quos, reprehenderit tempore tenetur voluptate! Ab eligendi, in iste nam nulla quas quis repellendus sequi.

At beatae debitis ducimus enim, officia saepe voluptatem voluptates? Ab, aut culpa dolor earum eos esse et excepturi facere fugiat fugit laboriosam minima mollitia necessitatibus nesciunt non quibusdam reprehenderit tenetur.

Code example

import { Dialog, Button } from '@yleisradio/yds-components-react';

<Dialog
  title="Dialog Title"
  actions={
    <>
      <Button text="Cancel" variant="text" />
      <Button text="Confirm" />
    </>
  }
>
  Dialog content goes here
</Dialog>

Why to use

Use Dialog to ensure consistent spacing, typography, scrolling behavior, and action placement across all dialog-based interfaces in YDS. Dialog standardizes dialog layout, handles internal scrolling and separators, aligns actions consistently across devices, and improves accessibility when used inside Modal or BottomSheet.

Important

Dialog is a building block component designed to work inside Modal or BottomSheet. It provides the content structure (title, body, actions) but does not provide modal behavior, backdrop, or focus management. Use Modal or BottomSheet for the actual dialog overlay functionality.

When to use

Use Dialog when you need a structured dialog layout that consists of a clear title, body content, and optional actions.

Do

• Use Dialog inside Modal or BottomSheet for all dialog interfaces.
• Use it for confirmations, forms, settings, and focused tasks.
• Use when content needs a clear hierarchy and actions footer.

Don't

• Don’t use Dialog as a standalone modal overlay.
• Don’t use it for generic layout or page content.
• Don’t omit the title — it is required for accessibility.

Content Guidelines

Use these guidelines when placing content inside a Dialog. They are based on the Modal content guidelines.

Do

• Write a clear, descriptive title that explains the task.
• Keep body content concise and task-focused.
• Match the primary action label to the dialog intent
• Action buttons should have clear, descriptive labels that indicate their purpose.

Don't

• Don’t overload the dialog with secondary content.
• Don’t include multi-step flows inside a dialog.
• Don’t use vague action labels like “OK”.

Key Dialog Props

Use these props to configure the Dialog component.

title

Dialog title text.

Type	Example	Description
string	Confirm Action Content	Title text for the dialog

Code example

<Dialog
  title="Confirm Action"
  actions={
    <>
      <Button variant="text" text="Cancel" />
      <Button text="Confirm" />
    </>
  }
>
  Are you sure you want to proceed?
</Dialog>

titleAs

HTML tag name to render for the title.

Type	Example	Description
string	Dialog Title Content	HTML element for title (e.g., 'h2')

Code example

<Dialog
  titleAs="h2"
  title="Dialog Title"
  actions={
    <>
      <Button variant="text" text="Cancel" />
      <Button text="Confirm" />
    </>
  }
>
  Content
</Dialog>

illustrativeIcon

Optional illustrative icon displayed above the title.

Type	Example	Description
React.ReactElement<SvgProps> | null	Title Content	Illustrative icon element to display

Code example

import { IllustrativeCelebrate } from '@yleisradio/yds-icons-react';

<Dialog
  illustrativeIcon={<IllustrativeCelebrate />}
  title="Dialog Title"
  actions={
    <>
      <Button variant="text" text="Cancel" />
      <Button text="Confirm" />
    </>
  }
>
  Content
</Dialog>

size

Size variant of the dialog.

Value	Example	Description
sm	Title Content	Small dialog size
md	Title Content	Medium dialog size (default)

Code example

<Dialog size="sm" title="Small Dialog" actions={<Button text="Action" />}>
  Content
</Dialog>
<Dialog size="md" title="Medium Dialog" actions={<Button text="Action" />}>
  Content
</Dialog>

actions

Action buttons or elements displayed in the footer.

Type	Example	Description
React.ReactNode	Title Content	Footer action elements

Code example

<Dialog
  title="Confirm"
  actions={
    <>
      <Button variant="text">Cancel</Button>
      <Button>Confirm</Button>
    </>
  }
>
  <p>Are you sure?</p>
</Dialog>

Behavior

• Dialog provides layout only — no open/close logic.
• Body content scrolls independently when height exceeds limits.
• Scroll separators appear automatically when content overflows.
• Actions remain visually separated from content.
• Action buttons in the actions prop are automatically sized to match the dialog's size prop
• Illustrative icons are positioned above the title and affect spacing accordingly
• The component is purely presentational — it does not handle opening, closing, or modal behavior (that's handled by Modal or BottomSheet)

Accessibility

• Title is rendered as a heading (default h2, configurable via titleAs prop) for proper document structure
  (WCAG 1.3.1 — Info and Relationships)
• Structure supports screen reader announcement when used in Modal/BottomSheet.
• Illustrative icons are decorative and don't require alt text (they're visual enhancements)

API Reference

Props

The Dialog component accepts all standard HTML <div> attributes in addition to the following props:

Prop	Type	Required	Default	Description
title	string	Yes	—	Dialog title text
titleAs	string	No	'h2'	HTML tag name to render for title
illustrativeIcon	React.ReactElement<SvgProps> | null	No	—	Optional icon displayed above title
size	'sm' | 'md'	No	'md'	Size variant of the dialog
children	React.ReactNode	No	—	Content displayed in dialog body
actions	React.ReactNode	No	—	Action buttons displayed in footer

Type Definitions

import { type SvgProps } from '@yleisradio/yds-icons-react';

export interface DialogDSProps {
  title: string;
  titleAs?: string;
  illustrativeIcon?: React.ReactElement<SvgProps> | null;
  size?: 'sm' | 'md';
  children?: React.ReactNode;
  actions?: React.ReactNode;
}

export type DialogProps = HTMLAttributes<HTMLDivElement> & DialogDSProps;

Related Components

• Modal – Primary container for Dialog — use Modal to wrap Dialog for desktop/tablet dialog interfaces.
• BottomSheet – Primary container for Dialog — use BottomSheet to wrap Dialog for mobile dialog interfaces.
• Button – Commonly used in dialog actions prop for footer buttons.
• Accordion – Can be used inside a Dialog to organise collapsible content.