Skip to content

Dialog

Use dialog component for all modals. It renders on top of the rest of the app with an overlay.
  • Alpha
  • Reviewed for accessibility

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
idString"dialog-#{(36**3 + rand(36**4)).to_s(36)}"The id of the dialog.
titleStringN/ADescribes the content of the dialog.
subtitleStringnilProvides additional context for the dialog, also setting the aria-describedby attribute.
sizeSymbol:mediumThe size of the dialog. One of :large, :medium, :medium_portrait, :small, or :xlarge.
positionSymbol:centerThe position of the dialog. One of :center, :left, or :right.
position_narrowSymbol:inheritThe position of the dialog when narrow. One of :bottom, :fullscreen, :inherit, :left, or :right.
visually_hide_titleBooleanfalseIf true will hide the heading title, while still making it available to Screen Readers.
system_argumentsHashN/ASystem arguments

Slots

show_button

Optional button to open the dialog.

NameTypeDefaultDescription
system_argumentsHashN/AThe same arguments as Button.

Header content.

NameTypeDefaultDescription
show_dividerBooleanN/AShow a divider between the header and body.
visually_hide_titleBooleanN/AVisually hide the title while maintaining a label for assistive technologies.
system_argumentsHashN/ASystem arguments

body

Required body content.

NameTypeDefaultDescription
system_argumentsHashN/ASystem arguments

Footer content.

NameTypeDefaultDescription
show_dividerBooleanN/AShow a divider between the footer and body.
system_argumentsHashN/ASystem arguments

Examples

Dialog with Cancel and Submit buttons

An ID is provided which enables wiring of the open and close buttons to the dialog.

Dialog Example

Some content

<%= render(Primer::Alpha::Dialog.new(
title: "Dialog Example",
id: "my-dialog",
)) do |d| %>
<% d.with_show_button { "Show Dialog" } %>
<% d.with_body do %>
<p>Some content</p>
<% end %>
<% d.footer do %>
<%= render(Primer::ButtonComponent.new(data: { "close-dialog-id": "my-dialog" })) { "Cancel" } %>
<%= render(Primer::ButtonComponent.new(scheme: :primary)) { "Submit" } %>
<% end %>
<% end %>