Native HTML dialog patterns for Rails with Turbo and Stimulus. Use when building modals, confirmations, alerts, or any overlay UI. Triggers on modal, dialog, popup, confirmation, alert, or toast patterns.
Build accessible modals, confirmations, and overlays using native HTML `<dialog>` with Turbo Frames and Stimulus. Triggers on requests for modals, dialogs, popups, confirmations, alerts, or toast notifications.
/plugin marketplace add majesticlabs-dev/majestic-marketplace/plugin install majestic-rails@majestic-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
resources/toast-slideover-patterns.mdresources/zero-js-patterns.mdBuild accessible, modern dialog UIs using the native HTML <dialog> element with Turbo Frames and Stimulus. No JavaScript frameworks or heavy libraries required.
<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 |
Modern browsers support the Invoker Commands API for declarative dialog control—no JavaScript required. See resources/zero-js-patterns.md for complete examples.
<%= 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>
| 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 |
| 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 |
@starting-style for enter/exit transitionsThe recommended pattern for Rails modals combines three technologies:
<dialog> - Accessible modal presentationAdd a modal turbo-frame to your layout:
<%# app/views/layouts/application.html.erb %>
<body>
<%= yield %>
<%# Modal injection point %>
<%= turbo_frame_tag :modal %>
</body>
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 } %>
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">×</button>
</header>
<%= render "form", post: @post %>
</article>
</dialog>
<% end %>
<% end %>
// app/javascript/controllers/dialog_controller.js
import { Controller } from "@hotwired/stimulus"
export default class extends Controller {
connect() {
// Auto-open when content loads via Turbo
this.element.showModal()
// Store original scroll position
this.scrollY = window.scrollY
}
disconnect() {
// Clean up turbo-frame to prevent stale content flash
const frame = this.element.closest("turbo-frame")
if (frame) {
frame.removeAttribute("src")
// Safe DOM clearing without innerHTML
frame.replaceChildren()
}
}
close() {
this.element.close()
}
clickOutside(event) {
// Close when clicking backdrop (the dialog element itself, not content)
if (event.target === this.element) {
this.close()
}
}
// Handle ESC key (native behavior, but can customize)
keydown(event) {
if (event.key === "Escape") {
this.close()
}
}
}
/* app/assets/stylesheets/components/dialog.css */
dialog {
border: none;
border-radius: 0.5rem;
padding: 0;
max-width: 32rem;
width: 90vw;
box-shadow: 0 25px 50px -12px rgb(0 0 0 / 0.25);
}
dialog::backdrop {
background: rgb(0 0 0 / 0.5);
backdrop-filter: blur(2px);
}
dialog article {
padding: 1.5rem;
}
dialog header {
display: flex;
justify-content: space-between;
align-items: center;
margin-bottom: 1rem;
}
/* Prevent background scroll when modal open */
body:has(dialog[open]) {
overflow: hidden;
}
With Tailwind:
<dialog class="rounded-lg shadow-xl max-w-lg w-[90vw] p-0 backdrop:bg-black/50 backdrop:backdrop-blur-sm"
data-controller="dialog"
data-action="click->dialog#clickOutside">
<!-- content -->
</dialog>
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.
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.
Re-render the form with 422 status to keep modal open:
render :new, status: :unprocessable_entity
To update content without closing:
def create
@post = Post.new(post_params)
if @post.save
respond_to do |format|
format.turbo_stream {
render turbo_stream: [
turbo_stream.append("posts", partial: "posts/post", locals: { post: @post }),
turbo_stream.update("modal", "") # Clear modal
]
}
format.html { redirect_to posts_path }
end
else
render :new, status: :unprocessable_entity
end
end
For destructive actions like delete:
<%# app/views/posts/confirm_delete.html.erb %>
<%= turbo_frame_tag :modal do %>
<dialog data-controller="dialog" data-action="click->dialog#clickOutside" open>
<article>
<h2>Delete Post?</h2>
<p>Are you sure you want to delete "<%= @post.title %>"? This cannot be undone.</p>
<footer class="flex gap-2 justify-end mt-4">
<button data-action="dialog#close" class="btn btn-secondary">
Cancel
</button>
<%= button_to "Delete", @post,
method: :delete,
class: "btn btn-danger",
data: { turbo_confirm: false } %>
</footer>
</article>
</dialog>
<% end %>
# config/routes.rb
resources :posts do
member do
get :confirm_delete
end
end
<%= link_to "Delete", confirm_delete_post_path(@post), data: { turbo_frame: :modal } %>
For flash messages and notifications. Use show() instead of showModal() for non-modal presentation. See resources/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).
For side panels (settings, filters, details). See resources/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>
Native <dialog> handles most accessibility, but verify:
showModal()<h2> or aria-labelledby<dialog aria-labelledby="dialog-title"
aria-describedby="dialog-description"
data-controller="dialog">
<h2 id="dialog-title">Confirm Action</h2>
<p id="dialog-description">This action cannot be undone.</p>
<!-- content -->
</dialog>
// Enhanced dialog controller with focus return
connect() {
this.previouslyFocused = document.activeElement
this.element.showModal()
}
close() {
this.element.close()
this.previouslyFocused?.focus()
}
| 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-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 |
# 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
| 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 resources/zero-js-patterns.md for progressive enhancement strategies.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.