Skip to content

Dialog ​

Dialog uses the native HTML <dialog> element under the hood which provides full accessibility out of the box and solves z-index issues by rendering the element in the top layer.

For a dialog pinned to the right edge of the screen, use a sheet.

Usage ​

erb
<button type="button">Open dialog</button>

<%= render(Impulse::DialogComponent.new(title: "My dialog")) do |c| %>
  <% c.with_body { "Dialog body" } %>
<% end %>
js
const button = document.querySelector('button');
const dialog = document.querySelector('awc-dialog');
button.addEventListener('click', () => {
  dialog.requestShow();
});

Arguments ​

Keyword arguments ​

NameDefaultDescription
titleN/AThe title of the dialog element, which names it.
idself.class.generate_idThe id of the dialog element.
size:mdThe size of the dialog element. One of :sm, :md, or :lg.
centertrueWhether or not to center the dialog vertically.
fullscreen:neverWhether or not to render the dialog fullscreen. One of :never, :always, :sm_down, :md_down, :lg_down, or :xl_down.
hide_on_outside_clicktrueWhether a press outside the dialog, released outside it, hides it.

Any other keyword arguments are passed to the <awc-dialog> element as HTML attributes.

Examples ​

Body ​

You can add any arbitrary rich content inside the body by calling the with_body slot.

erb
<%= render(Impulse::DialogComponent.new(title: "My dialog")) do |c| %>
  <% c.with_body do %>
    <p>Dialog body</p>
  <% end %>
<% end %>

You can add a footer by calling the with_footer slot.

erb
<%= render(Impulse::DialogComponent.new(title: "My dialog")) do |c| %>
  <% c.with_footer do %>
    <button type="button">Submit</button>
  <% end %>
<% end %>

Custom header ​

The header renders its block between the title and the close button.

erb
<%= render(Impulse::DialogComponent.new(title: "Edit profile")) do |c| %>
  <% c.with_header(class: "align-items-center") do %>
    <span class="badge badge-secondary">Draft</span>
  <% end %>
  <% c.with_body { "Dialog body" } %>
<% end %>

Hiding the title ​

Hide the title with visually_hide_title: true, such as when a search field takes its place. It still names the dialog for assistive technology.

erb
<%= render(Impulse::DialogComponent.new(title: "Command palette")) do |c| %>
  <% c.with_header(visually_hide_title: true) do %>
    <input type="search" placeholder="Search..." aria-label="Search">
  <% end %>
  <% c.with_body { "Dialog body" } %>
<% end %>

Hiding the close button ​

Leave the close button out with hide_close_button: true. Escape and a click outside still close the dialog. Give it another button that closes it, as below, when hide_on_outside_click is off.

erb
<%= render(Impulse::DialogComponent.new(title: "Delete project")) do |c| %>
  <% c.with_header(hide_close_button: true) %>
  <% c.with_footer do %>
    <button type="button" data-action="click->awc-dialog#requestHide">Cancel</button>
  <% end %>
<% end %>

With both hidden, the header shows only its block.

erb
<%= render(Impulse::DialogComponent.new(title: "Command palette")) do |c| %>
  <% c.with_header(visually_hide_title: true, hide_close_button: true) do %>
    <input type="search" placeholder="Search..." aria-label="Search">
  <% end %>
  <% c.with_body { "Dialog body" } %>
<% end %>

Without a block either, the header isn't rendered.

Adding a form ​

When the block renders content of its own, such as a form, the dialog renders that content instead of the with_body and with_footer slots. Render the slots inside it with <%= %>, and give the element that wraps them the awc-dialog--scrollable class, so that only the body scrolls.

erb
<%= render(Impulse::DialogComponent.new(title: "Edit profile")) do |c| %>
  <%= form_with url: "#", class: "awc-dialog--scrollable" do |f| %>
    <%= c.with_body do %>
      <%= f.label :name %>
      <%= f.text_field :name %>
    <% end %>
    <%= c.with_footer do %>
      <button type="reset" data-action="click->awc-dialog#requestHide">Cancel</button>
      <%= f.submit %>
    <% end %>
  <% end %>
<% end %>

If your arbitrary content comes from a partial as is the case with many form_with partials, you can use the Impulse::Dialog::BodyComponent and Impulse::Dialog::FooterComponent to render the body and footer of the dialog component respectively.

erb
<%= render(Impulse::DialogComponent.new(title: "Edit profile")) do %>
  <%= render "shared/form" %>
<% end %>
erb
<%# app/views/shared/_form.html.erb %>

<%= form_with url: "#", class: "awc-dialog--scrollable" do |f| %>
  <%= render(Impulse::Dialog::BodyComponent.new) do %>
    <%= f.label :name %>
    <%= f.text_field :name %>
  <% end %>
  <%= render(Impulse::Dialog::FooterComponent.new) do %>
    <button type="reset" data-action="click->awc-dialog#requestHide">Cancel</button>
    <%= f.submit %>
  <% end %>
<% end %>

Closing the dialog ​

Add the data-action="click->awc-dialog#requestHide" attribute on the button element to close the dialog when clicking it.

requestHide emits the cancelable awc-dialog:hide event first, so a listener can keep the dialog open, for example while a form inside it has unsaved changes. hide closes it without asking.

erb
<%= render(Impulse::DialogComponent.new(title: "Edit your profile")) do |c| %>
  <% c.with_body do %>
    <button type="button" data-action="click->awc-dialog#requestHide">Close</button>
  <% end %>
<% end %>

Nested dialogs ​

You can nest as many dialogs as you want and it will be stacked on top of the parent dialog.

erb
<button type="button">Open dialog</button>

<%= render(Impulse::DialogComponent.new(title: "Edit your profile")) do |c| %>
  <% c.with_body do %>
    <p>Body contents...</p>
    <button type="button">Open nested dialog</button>
    <%= render(Impulse::DialogComponent.new(title: "Nested dialog", size: :sm)) do |nested| %>
      <% nested.with_body { "This is a nested dialog." } %>
    <% end %>
  <% end %>
<% end %>

Slots ​

with_header ​

The header of the dialog, which holds its title and close button.

NameDefaultDescription
visually_hide_titlefalseWhether or not to hide the title, which still names the dialog.
hide_close_buttonfalseWhether or not to leave out the close button.
system_args{}HTML attributes for the slot's element.

with_body ​

The body of the dialog.

NameDefaultDescription
system_args{}HTML attributes for the slot's element.

The footer of the dialog.

NameDefaultDescription
system_args{}HTML attributes for the slot's element.

Imports ​

js
import '@ambiki/impulse-view-components/dialog';
scss
@import '@ambiki/impulse-view-components/dialog';

The styles need Bootstrap's Sass and the base styles loaded first. See Import the styles.

JS API ​

Read here.

Released under the MIT License.