Build accessible, modern dialog UIs using the native HTML `<dialog>` element with Turbo Frames and Stimulus. No JavaScript frameworks or heavy libraries required.

Supporting Files

references/dialog-examples.mdreferences/toast-slideover-patterns.mdreferences/zero-js-patterns.md

SKILL.md

262 lines · ~2.3k tokens

Stats

LanguageShell

Parent stars39

Parent forks7

MaintenanceExcellent

Last CommitApr 4, 2026

Actions

View Source View Plugin View on GitHub View README

Native Dialog Patterns for Rails

Build accessible, modern dialog UIs using the native HTML <dialog> element with Turbo Frames and Stimulus. No JavaScript frameworks or heavy libraries required.

When to Use This Skill

Building modal dialogs for forms, confirmations, or content
Creating toast/alert notifications
Implementing confirmation dialogs (delete, destructive actions)
Any overlay UI that needs focus management and accessibility

Why Native `<dialog>`?

Feature	Native `<dialog>`	Custom Modal
Focus trapping	Built-in	Manual implementation
ESC to close	Built-in	Manual implementation
Backdrop	Built-in (`::backdrop`)	Manual overlay
Accessibility	Native `role="dialog"`	Manual ARIA
Top layer	Automatic (above all content)	z-index battles
Scroll lock	Automatic	Manual `overflow: hidden`

Zero-JavaScript Confirmation Dialogs (Recommended)

Modern browsers support the Invoker Commands API for declarative dialog control—no JavaScript required. See references/zero-js-patterns.md for complete examples.

Quick Reference

<%= button_tag "Delete", commandfor: "delete-#{post.id}", command: "show-modal" %>

<dialog id="delete-<%= post.id %>" closedby="any" role="alertdialog">
  <h3>Delete "<%= post.title %>"?</h3>
  <button commandfor="delete-<%= post.id %>" command="close">Cancel</button>
  <%= button_to "Delete", post, method: :delete %>
</dialog>

Key Attributes

Attribute	Purpose
`commandfor="id"`	References the dialog to control
`command="show-modal"`	Opens as modal (backdrop, focus trap)
`command="close"`	Closes the dialog
`closedby="any"`	Enables backdrop click and ESC to close

When to Use Zero-JS vs Stimulus

Scenario	Approach
Simple confirmations	Zero-JS (Invoker Commands)
Modals with async content	Stimulus + Turbo Frames
Complex multi-step dialogs	Stimulus controller
Animations	CSS `@starting-style`

Additional Patterns (see references/)

CSS animations with @starting-style for enter/exit transitions
Turbo.config.forms.confirm to replace ugly browser dialogs
Progressive enhancement for cross-browser compatibility

Core Pattern: Async Modal with Turbo Frames

The recommended pattern for Rails modals combines three technologies:

Turbo Frame - Async content loading without page reload
Native <dialog> - Accessible modal presentation
Stimulus controller - Lifecycle management

Step 1: Layout Container

Add a modal turbo-frame to your layout:

<%# app/views/layouts/application.html.erb %>
<body>
  <%= yield %>

  <%# Modal injection point %>
  <%= turbo_frame_tag :modal %>
</body>

Step 2: Trigger Links

Target the modal frame from any link:

<%# Any view %>
<%= link_to "New Post", new_post_path, data: { turbo_frame: :modal } %>
<%= link_to "Edit", edit_post_path(@post), data: { turbo_frame: :modal } %>
<%= link_to "Confirm Delete", confirm_delete_post_path(@post), data: { turbo_frame: :modal } %>

Step 3: Modal Content View

Wrap modal content in matching turbo-frame with nested inner frame:

<%# app/views/posts/new.html.erb %>
<%= turbo_frame_tag :modal do %>
  <%# Inner frame prevents flash during form validation %>
  <%= turbo_frame_tag :modal_content do %>
    <dialog data-controller="dialog" data-action="click->dialog#clickOutside" open>
      <article>
        <header>
          <h2>New Post</h2>
          <button data-action="dialog#close" aria-label="Close">&times;</button>
        </header>

        <%= render "form", post: @post %>
      </article>
    </dialog>
  <% end %>
<% end %>

Step 4: Stimulus Controller

Key behaviors: showModal() on connect, replaceChildren() on disconnect (prevents stale content), clickOutside for backdrop close.

See references/dialog-examples.md for full Stimulus controller, CSS styling, and Tailwind variant.

Why Nested Turbo Frames?

The nested frame pattern (modal > modal_content) prevents content flashing:

<%= turbo_frame_tag :modal do %>
  <%= turbo_frame_tag :modal_content do %>
    <dialog>...</dialog>
  <% end %>
<% end %>

Problem without nested frame: When a form inside the modal has validation errors and re-renders, the outer frame briefly shows the old content before replacing it.

Solution with nested frame: The inner frame handles form re-renders independently, keeping the modal structure stable.

Form Handling in Modals

Successful Submission

Redirect with Turbo to close modal and update page:

# app/controllers/posts_controller.rb
def create
  @post = Post.new(post_params)

  if @post.save
    redirect_to posts_path, notice: "Post created!"
  else
    render :new, status: :unprocessable_entity
  end
end

The redirect navigates _top (full page), effectively closing the modal.

Validation Errors

Re-render the form with 422 status to keep modal open:

render :new, status: :unprocessable_entity

Turbo Stream Response (Stay in Modal)

Use turbo_stream.update("modal", "") to clear modal without full redirect. See references/dialog-examples.md for full example.

Confirmation Dialog Pattern

For destructive actions: add a confirm_delete member route, render a dialog in a turbo frame, trigger via link_to with data: { turbo_frame: :modal }.

See references/dialog-examples.md for full confirmation dialog view, route, and trigger.

Alert/Toast Pattern

For flash messages and notifications. Use show() instead of showModal() for non-modal presentation. See references/toast-slideover-patterns.md for complete implementation.

<dialog class="toast" data-controller="toast" data-toast-duration-value="5000">
  <p><%= message %></p>
</dialog>

Key difference: show() opens without backdrop or focus trap (toasts), showModal() centers with backdrop (modals).

Slideover Panel Pattern

For side panels (settings, filters, details). See references/toast-slideover-patterns.md for styling and animations.

<dialog class="slideover" data-controller="dialog" data-action="click->dialog#clickOutside">
  <aside>
    <header><h2>Filters</h2></header>
    <%= render "filters" %>
  </aside>
</dialog>

Accessibility

Native <dialog> provides focus trapping, ESC close, background inert, and top layer automatically. Additionally ensure:

Visible close button (not just ESC)
aria-labelledby / aria-describedby for descriptive context
Focus return to trigger element on close (store document.activeElement in connect())

See references/dialog-examples.md for enhanced accessibility and focus return examples.

Common Patterns Summary

Pattern	Container	Stimulus	`show` method
Modal form	`turbo_frame_tag :modal`	`dialog`	`showModal()`
Confirmation	`turbo_frame_tag :modal`	`dialog`	`showModal()`
Toast/Alert	Fixed position	`toast`	`show()`
Slideover	`turbo_frame_tag :modal`	`dialog`	`showModal()`

Anti-Patterns to Avoid

Anti-Pattern	Problem	Solution
Custom modal without `<dialog>`	No native accessibility	Use native `<dialog>`
Missing nested turbo-frame	Content flash on validation	Add inner frame
Not clearing frame on close	Stale content on reopen	Clear with `replaceChildren()` in `disconnect()`
z-index for stacking	Battles with other elements	`<dialog>` uses top layer
Manual focus trap	Complex, error-prone	`showModal()` handles it
Inline backdrop div	Extra markup	Use `::backdrop` pseudo-element

Testing Dialogs

# System test - use `within "dialog"` to scope assertions
within "dialog" do
  fill_in "Title", with: "My Post"
  click_button "Create"
end
expect(page).not_to have_selector("dialog[open]")  # Modal closed

Browser Support

Pattern	Chrome	Firefox	Safari
Native `<dialog>`	37+	98+	15.4+
Invoker Commands	135+	144+	26.2+
`@starting-style`	117+	129+	17.5+

For older browsers: dialog polyfill, invokers polyfill. See references/zero-js-patterns.md for progressive enhancement strategies.

dialog-patterns

Popularity

Invocation

Context Preview

Supporting Files

SKILL.md

dialog-patterns

Popularity

Invocation

Context Preview

Supporting Files

SKILL.md

Native Dialog Patterns for Rails

When to Use This Skill

Why Native <dialog>?

Zero-JavaScript Confirmation Dialogs (Recommended)

Quick Reference

Key Attributes

When to Use Zero-JS vs Stimulus

Additional Patterns (see references/)

Core Pattern: Async Modal with Turbo Frames

Step 1: Layout Container

Step 2: Trigger Links

Step 3: Modal Content View

Step 4: Stimulus Controller

Why Nested Turbo Frames?

Form Handling in Modals

Successful Submission

Validation Errors

Turbo Stream Response (Stay in Modal)

Confirmation Dialog Pattern

Alert/Toast Pattern

Slideover Panel Pattern

Accessibility

Common Patterns Summary

Anti-Patterns to Avoid

Testing Dialogs

Browser Support

Similar Skills

Native Dialog Patterns for Rails

When to Use This Skill

Why Native <dialog>?

Zero-JavaScript Confirmation Dialogs (Recommended)

Quick Reference

Key Attributes

When to Use Zero-JS vs Stimulus

Additional Patterns (see references/)

Core Pattern: Async Modal with Turbo Frames

Step 1: Layout Container

Step 2: Trigger Links

Step 3: Modal Content View

Step 4: Stimulus Controller

Why Nested Turbo Frames?

Form Handling in Modals

Successful Submission

Validation Errors

Turbo Stream Response (Stay in Modal)

Confirmation Dialog Pattern

Alert/Toast Pattern

Slideover Panel Pattern

Accessibility

Common Patterns Summary

Anti-Patterns to Avoid

Testing Dialogs

Browser Support

Similar Skills

Why Native `<dialog>`?

Why Native `<dialog>`?