Dialog

Dialog is a floating surface used to display transient content such as confirmation actions, selection options, and more.

v0.34.0AlphaReviewed for accessibility

Description

A Dialog is used to remove the user from the main application flow, to confirm actions, ask for disambiguation or to present small forms.

Accessibility

  • Dialog Accessible Name: A dialog should have an accessible name, so screen readers are aware of the purpose of the dialog when it opens. Give an accessible name setting :title. The accessible name will be used as the main heading inside the dialog.
  • Dialog unique id: A dialog should be unique. Give a unique id setting :dialog_id. If no :dialog_id is given, a default randomize hex id is generated.

The combination of both :title and :dialog_id establishes an aria-labelledby relationship between the title and the unique id of the dialog.

Arguments

NameTypeDefaultDescription
id
String

self.class.generate_id

The id of the dialog.

title
String

N/A

Describes the content of the dialog.

subtitle
String

nil

Provides additional context for the dialog, also setting the aria-describedby attribute.

size
Symbol

:medium

The size of the dialog. One of :auto, :large, :medium, :medium_portrait, :small, or :xlarge.

position
Symbol

:center

The position of the dialog. One of :center, :left, or :right.

position_narrow
Symbol

:inherit

The position of the dialog when narrow. One of :bottom, :fullscreen, :inherit, :left, or :right.

visually_hide_title
Boolean

false

If true will hide the heading title, while still making it available to Screen Readers.

system_arguments
Hash

N/A

Examples

Slots

show_button

Optional button to open the dialog.

NameTypeDefaultDescription
system_arguments
Hash

N/A

The same arguments as Button.

Header content.

NameTypeDefaultDescription
show_divider
Boolean

N/A

Show a divider between the header and body.

visually_hide_title
Boolean

N/A

Visually hide the title while maintaining a label for assistive technologies.

system_arguments
Hash

N/A

The arguments accepted by Dialog::Header.

body

Required body content.

NameTypeDefaultDescription
system_arguments
Hash

N/A

Footer content.

NameTypeDefaultDescription
show_divider
Boolean

N/A

Show a divider between the footer and body.

system_arguments
Hash

N/A

Methods

id

The dialog's ID value.

Dialog::Header

A Dialog::Header is a compositional component, used to render the Header of a dialog. See Dialog.

Arguments

NameTypeDefaultDescription
id
String

N/A

The HTML element's ID value.

title
String

N/A

Describes the content of the dialog.

subtitle
String

nil

Provides additional context for the dialog, also setting the aria-describedby attribute.

show_divider
Boolean

false

Show a divider between the header and body.

visually_hide_title
Boolean

false

Visually hide the title while maintaining a label for assistive technologies.

variant
Symbol

:medium

One of :large or :medium.

system_arguments
Hash

N/A

Slots

filter

Optional filter slot for adding a filter input to the header.

NameTypeDefaultDescription
system_arguments
Hash

N/A

subtitle

Optional subtitle slot for adding a subtitle to the header.

NameTypeDefaultDescription
system_arguments
Hash

N/A

Dialog::Body

A Dialog::Body is a compositional component, used to render the Body of a dialog. See Dialog.

Arguments

NameTypeDefaultDescription
system_arguments
Hash

N/A

Dialog::Footer

A Dialog::Footer is a compositional component, used to render the Footer of a dialog. See Dialog.

Arguments

NameTypeDefaultDescription
show_divider
Boolean

false

Show a divider between the footer and body.

system_arguments
Hash

N/A