# 🍬 swal_rails **SweetAlert2 v11 for Rails 7+ — batteries included.** First-class support for **Importmap**, **jsbundling**, and **Sprockets**, with a Stimulus controller, auto-wired flash messages, Turbo confirm replacement, Ruby view helpers, and full I18n. Everything is configurable. [](https://github.com/Metalzoid/swal_rails/actions) [](https://rubygems.org/gems/swal_rails) [](https://www.ruby-lang.org/) [](https://rubyonrails.org/) [](https://sweetalert2.github.io/) [](LICENSE.txt)

---

📖 Table of contents

• Why swal_rails?
• Features
• Compatibility
• Installation
• Quick start
• Configuration
• Usage
  • Flash messages
  • Turbo confirmations
  • data-swal-confirm attribute
  • Multi-step confirmations
  • Stimulus controller
  • Ruby view helpers
  • Programmatic JS
• Reference
  • SwalRails.configure
  • View helpers
  • Data attributes
  • Stimulus controller reference
  • JS runtime
  • Generators
  • Flash value shapes
  • Chain semantics
• I18n
• Accessibility
• Security & CSP
• Themes
• Asset pipelines
• Development
• Contributing
• Credits & license

---

🤔 Why swal_rails?

The existing gems haven't shipped a release since 2019 (SA2 was on v7 back then — it's on v11 now) and were built for the Rails 5 / UJS era. swal_rails is the modern replacement:

	sweetalert2-rails	sweetify	swal_rails
SweetAlert2 v11.x	❌	❌	✅
Rails 7+ / Turbo-native	❌	❌	✅
Importmap	❌	❌	✅
jsbundling (esbuild / vite / rollup)	❌	❌	✅
Sprockets	✅	❌	✅
Stimulus controller	❌	❌	✅
Flash auto-wire, map per key	❌	partial	✅
Turbo setConfirmMethod override	❌	❌	✅
data-swal-confirm attribute	❌	❌	✅
Ruby view helpers (swal_tag)	❌	❌	✅
I18n Rails (fr/en shipped)	❌	❌	✅
a11y (reduced-motion, ARIA)	❌	❌	✅
Last release	2019	2019	maintained

---

✨ Features

• 🎨 SweetAlert2 v11 vendored and pinned — no CDN, no surprise upgrades.
• ⚡ Three asset pipelines: Importmap (default), jsbundling, Sprockets.
• 🔔 Auto-wired flash — flash[:notice] → toast, flash[:alert] → modal, fully mappable per key.
• 🛡️ Turbo confirmations — replace the native confirm() globally or opt-in per element.
• 🎮 Stimulus controller (data-controller="swal") for declarative popups.
• 🧱 Ruby view helpers — swal_tag, swal_config_meta_tag, swal_flash_meta_tag.
• 🔒 CSP-friendly — swal_tag(..., nonce: true) propagates the per-request nonce.
• 🌍 I18n ready — en / fr locales shipped, override freely.
• ♿ Accessibility — honors prefers-reduced-motion, preserves ARIA & focus trap.
• 🧩 Engine-based — zero monkey-patching, follows Rails Engine conventions.

---

🔧 Compatibility

Tested on every combination of Ruby and Rails listed below via the Appraisal gem:

	Rails 7.2	Rails 8.0	Rails 8.1.3	Rails 8.1.3 + Sprockets
Ruby 3.2	✅	✅	✅	✅
Ruby 3.3	✅	✅	✅	✅
Ruby 3.4	✅	✅	✅	✅
Ruby 3.5	✅	✅	✅	✅
Ruby 4.0	—	✅	✅	✅

Requirements: Ruby ≥ 3.2 (tested up to 4.0), Rails ≥ 7.2 (tested up to 8.1.3), Turbo recommended.

---

📦 Installation

Add this line to your application's Gemfile:

gem "swal_rails"

During the beta, pin the prerelease explicitly:

gem "swal_rails", "0.3.1.beta1"

or install globally with gem install swal_rails --pre. Bundler ignores prereleases unless you ask for one.

Then install and run the generator:

$ bundle install
$ bin/rails g swal_rails:install

The generator autodetects your asset pipeline. You can force it:

$ bin/rails g swal_rails:install --mode=importmap   # default for new Rails apps
$ bin/rails g swal_rails:install --mode=jsbundling  # esbuild, vite, rollup
$ bin/rails g swal_rails:install --mode=sprockets   # legacy apps

What the generator does

• 📄 creates config/initializers/swal_rails.rb
• 📌 pins (Importmap) or adds (jsbundling/sprockets) sweetalert2 and swal_rails
• 💉 injects <%= swal_rails_meta_tags %> into app/views/layouts/application.html.erb
• 🌐 loads the en / fr locales

Finally, in your JS entrypoint (e.g. app/javascript/application.js):

import "swal_rails"

---

🚀 Quick start

Thirty seconds, tops. After running the installer:

# app/controllers/posts_controller.rb
def create
  @post = Post.create!(post_params)
  redirect_to @post, notice: "Post created!"
end

<%# app/views/posts/show.html.erb %>
<%= button_to "Delete", @post, method: :delete,
      data: { turbo_confirm: "Really delete this post?" } %>

That's it. notice renders as a toast, the delete button opens a SweetAlert2 modal instead of the browser's ugly native confirm().

---

⚙️ Configuration

Everything lives in config/initializers/swal_rails.rb:

SwalRails.configure do |config|
  # ─── Confirm behavior ────────────────────────────────────────────────
  # :off            → don't touch Turbo, no data-attribute listener
  # :data_attribute → only intercept [data-swal-confirm] clicks (default)
  # :turbo_override → replace Turbo.setConfirmMethod globally
  # :both           → data-attribute + Turbo override
  config.confirm_mode = :data_attribute

  # ─── UX ──────────────────────────────────────────────────────────────
  config.respect_reduced_motion = true   # disable animations when OS asks
  config.expose_window_swal     = true   # window.Swal for console hacking

  # ─── Defaults passed to every Swal.fire call ─────────────────────────
  config.default_options = {
    buttonsStyling: true,
    reverseButtons: false,
    focusConfirm:   true,
    returnFocus:    true
  }

  # ─── Flash → Swal mapping (per key) ──────────────────────────────────
  config.flash_map[:notice]  = { icon: "success", toast: true,  position: "top-end", timer: 3000 }
  config.flash_map[:success] = { icon: "success", toast: true,  position: "top-end", timer: 3000 }
  config.flash_map[:alert]   = { icon: "error",   toast: false }
  config.flash_map[:error]   = { icon: "error",   toast: false }
  config.flash_map[:warning] = { icon: "warning", toast: true,  position: "top-end", timer: 4000 }
  config.flash_map[:info]    = { icon: "info",    toast: true,  position: "top-end", timer: 3000 }

  # ─── I18n scope (for button labels) ──────────────────────────────────
  config.i18n_scope = "swal_rails"
end

💡 Per-key override tip: to disable the toast for a single key without rewriting the whole map: config.flash_map[:alert] = { icon: "error", toast: false }.

---

🎯 Usage

Flash messages

Any flash set from a controller is rendered automatically on page load:

flash[:notice] = "Profile updated"   # → toast top-right
flash[:alert]  = "Could not save"    # → modal

Arrays are expanded into one popup per message — handy for model errors:

flash[:alert] = @post.errors.full_messages  # ["Title can't be blank", "Body is too short"]
# → two separate Swals, one per message

Need to override the per-key defaults for a single request? Assign a Hash instead of a String — its keys flow straight into Swal.fire and shadow flash_map[key]:

flash[:notice] = { text: "Deployed!", icon: "rocket", timer: 5000, toast: true }
# → ignores flash_map[:notice], fires a 5-second rocket toast

Behind the scenes, the engine serializes the flash into a meta tag (<meta name="swal-flash" content="...">) and the JS runtime reads it and calls Swal.fire(...) with your per-key options.

---

Turbo confirmations

Works with standard Rails / Turbo syntax:

<%= button_to "Delete", post_path(@post), method: :delete,
      data: { turbo_confirm: "Really delete?" } %>

When confirm_mode is :turbo_override or :both, swal_rails replaces Turbo.setConfirmMethod with a SweetAlert2-backed implementation — the same data-turbo-confirm attribute now shows a proper modal.

Pass a Hash instead of a string to carry full SA2 options:

<%= button_to "Delete", post_path(@post), method: :delete, data: {
      turbo_confirm: { icon: "error", title: "Really?", confirmButtonText: "Nuke" }
    } %>

Rails JSON-encodes the Hash into the attribute; the runtime parses it back and treats it as a full options object (same thing works with data-swal-confirm).

---

data-swal-confirm attribute

If you don't want to override Turbo globally, opt-in per element:

<%= link_to "Archive", archive_path,
      data: { swal_confirm: "Archive this item?", swal_icon: "warning" } %>

Supported data attributes:

Attribute	Maps to
data-swal-confirm	text / title prompt
data-swal-title	title
data-swal-text	text
data-swal-icon	icon
data-swal-confirm-text	confirmButtonText
data-swal-cancel-text	cancelButtonText
data-swal-options (JSON)	full SA2 options (wins over the above)

Use data-swal-options when you need anything beyond the shortcuts — it accepts any SweetAlert2 option:

<%= button_to "Delete", post_path(@post), method: :delete, data: {
      swal_confirm: "Danger",
      swal_options: { icon: "error", iconColor: "#ff0000", confirmButtonText: "Nuke" }.to_json
    } %>

---

Multi-step confirmations

For destructive flows (account deletion, legal opt-ins, irreversible actions), chain several popups via data-swal-steps. Each step only fires if the previous one was confirmed — any Cancel or Esc aborts the whole cascade, and the original click/submit never reaches the server:

<%= button_to "Delete account", account_path, method: :delete, data: {
      swal_steps: [
        { title: "Delete your account?", icon: "warning" },
        { title: "This cannot be undone", icon: "error" },
        { title: "Type DELETE to confirm", input: "text" }
      ].to_json
    } %>

Every step is a full SweetAlert2 options Hash — override the default icon, buttons, timer, input: type, anything SA2 accepts. The per-step defaults (showCancelButton: true, focusCancel: true, icon: "warning") are merged in first and can be replaced key-by-key.

Conditional branching (onConfirmed / onDenied)

Add a Deny button (showDenyButton: true) to get a three-way choice, and attach a nested sub-chain to either outcome:

<%= button_to "Delete or disable?", account_path, method: :delete, data: {
      swal_steps: [
        {
          title: "Delete or just disable?",
          icon: "question",
          showDenyButton: true,
          confirmButtonText: "Delete forever",
          denyButtonText:    "Disable for 30 days",
          onDenied: [
            { title: "Confirm disable", icon: "info" }
          ]
        }
      ].to_json
    } %>

Semantic rules, per step:

SA2 result	Behavior
isDismissed	Abort the entire chain; action does not fire
isConfirmed	Run onConfirmed sub-chain if present (replaces remainder); else continue linearly
isDenied	Run onDenied sub-chain if present (its result decides); else abort

Sub-chains are recursive — they're just nested arrays of steps.

Under confirm_mode = :turbo_override (or :both), passing a JSON array to data-turbo-confirm works the same way:

<%= button_to "Delete", account_path, method: :delete, data: {
      turbo_confirm: [
        { title: "Really?" },
        { title: "Really really?" }
      ]
    } %>

From Ruby, the view helper swal_chain_tag fires a chain inline on page load (same CSP nonce and XSS hardening as swal_tag):

<%= swal_chain_tag([
      { title: "Welcome back" },
      { title: "Accept updated terms?" }
    ]) %>

---

Stimulus controller

For fully declarative popups without touching JS:

<button data-controller="swal"
        data-action="click->swal#fire"
        data-swal-options-value='{"title":"Hello","icon":"success"}'>
  Ping
</button>

Available actions: fire, confirm, chain. The chain action reads data-swal-steps-value (same shape as data-swal-steps) and submits the enclosing form if every step resolves confirmed.

---

Ruby view helpers

Fire a one-shot popup directly from a view:

<%= swal_tag(title: "Welcome back!", icon: "info", timer: 2000) %>

Under a strict Content Security Policy, pass nonce: true — Rails fills in the per-request nonce so the inline <script> survives the policy:

<%= swal_tag({ title: "Welcome back!" }, nonce: true) %>

Heads-up: the emitted tag is <script type="module"> with a bare import Swal from "sweetalert2". That resolves via Importmap (or any shim that processes import maps). On a pure esbuild/webpack setup with no importmap tag on the page, prefer the Stimulus controller or call window.Swal.fire(...) from your bundle instead.

Lower-level helpers (injected by the generator into your layout):

<%= swal_rails_meta_tags %>
<%# expands to: %>
<%= swal_config_meta_tag %>  <%# serializes SwalRails.configuration %>
<%= swal_flash_meta_tag %>   <%# serializes current flash, if any %>

---

Programmatic JS

Swal is re-exported from the gem's JS runtime:

import Swal from "sweetalert2"

Swal.fire({
  title: "Saved!",
  icon: "success",
  toast: true,
  position: "top-end",
  timer: 3000
})

If config.expose_window_swal = true, window.Swal is also available for quick console debugging.

---

📘 Reference

Complete, at-a-glance specification of every public surface the gem exposes. The sections above give narrative walk-throughs — this section is the lookup table.

SwalRails.configure

SwalRails.configure { |config| ... }       # block form, yields Configuration
SwalRails.configuration                    # reader — memoized, safe to mutate
SwalRails.reset_configuration!             # resets to defaults (test fixture helper)

Configuration attributes

Attribute	Type	Default	Description
confirm_mode	Symbol	:data_attribute	Routing of confirm dialogs — see values below. Validated: assignment with any other value raises ArgumentError. Strings are coerced to symbols.
flash_keys_as_meta	Boolean	true	When false, swal_flash_meta_tag returns nil — useful to opt out without removing the swal_rails_meta_tags call from the layout.
respect_reduced_motion	Boolean	true	When the OS reports prefers-reduced-motion: reduce, the gem empties SA2's showClass / hideClass to suppress animations.
expose_window_swal	Boolean	true	When true, window.Swal is set to the mixed-in Swal instance after boot (useful for console debugging and inline scripts).
default_options	Hash	see below	Merged into every Swal.fire(...) call via Swal.mixin(...).
flash_map	Hash	see below	Flash-key → SA2 options mapping. Keys normalized to symbols. Non-Hash assignment raises ArgumentError.
i18n_scope	String	"swal_rails"	I18n scope used to look up confirm_button_text, cancel_button_text, deny_button_text, close_button_aria_label. Non-string values are coerced.

confirm_mode accepted values:

Value	Behavior
:off	No Turbo override, no data-attribute listener. Use Swal manually.
:data_attribute	(default) intercept clicks/submits on [data-swal-confirm] and [data-swal-steps]. Does not touch Turbo.
:turbo_override	Replaces Turbo.setConfirmMethod globally. data-turbo-confirm attributes open SA2 modals.
:both	Enables both mechanisms — useful for mixed codebases migrating over.

default_options default:

{ buttonsStyling: true, reverseButtons: false, focusConfirm: true, returnFocus: true }

flash_map default (per key, all overridable):

{
  notice:  { icon: "success", toast: true,  position: "top-end", timer: 3000, timerProgressBar: true, showConfirmButton: false },
  success: { icon: "success", toast: true,  position: "top-end", timer: 3000, timerProgressBar: true, showConfirmButton: false },
  alert:   { icon: "error",   toast: false, timer: nil },
  error:   { icon: "error",   toast: false, timer: nil },
  warning: { icon: "warning", toast: true,  position: "top-end", timer: 4000, timerProgressBar: true, showConfirmButton: false },
  info:    { icon: "info",    toast: true,  position: "top-end", timer: 3000, timerProgressBar: true, showConfirmButton: false }
}

to_client_payload (internal, read-only)

Serialization contract consumed by the JS runtime via the <meta name="swal-config"> tag. Returns:

{
  confirmMode:          Symbol,
  respectReducedMotion: Boolean,
  exposeWindowSwal:     Boolean,
  defaultOptions:       Hash,
  flashMap:             Hash,
  i18n:                 Hash   # only keys whose translation is present
}

---

View helpers

All helpers are injected into both ActionController::Base and ActionView::Base by the engine; they are available in every view and in every controller-side rendering context.

Helper	Returns	Description
swal_rails_meta_tags	ActiveSupport::SafeBuffer	Emits swal_config_meta_tag + swal_flash_meta_tag joined with "\n". Call once, in <head>.
swal_config_meta_tag	ActiveSupport::SafeBuffer	Emits <meta name="swal-config" content="…JSON…"> with the serialized SwalRails.configuration.to_client_payload.
swal_flash_meta_tag	ActiveSupport::SafeBuffer or nil	Emits <meta name="swal-flash" content="…JSON…"> if flash_keys_as_meta is enabled and the current flash is non-empty; otherwise returns nil.
swal_tag(options, html_options)	ActiveSupport::SafeBuffer	Inline <script type="module"> firing Swal.fire(options) once. Options are JSON-escaped to neutralize </script>, <!--, U+2028, U+2029.
swal_chain_tag(steps, html_options)	ActiveSupport::SafeBuffer	Inline <script type="module"> firing chainDialogs(Swal, steps). steps is an Array of Hashes (single Hash is auto-wrapped). Same escape hardening as swal_tag.

html_options (for swal_tag / swal_chain_tag)

• nonce: true → propagates the per-request CSP nonce (when Rails exposes content_security_policy_nonce). Silently dropped when no CSP helper is configured, so the helper stays safe in apps without CSP.
• Any other key is forwarded to javascript_tag as <script> attributes.

The default type is "module" — override with html_options = { type: "text/javascript" } if you need a classic script.

⚠️ The emitted <script type="module"> contains bare imports (import Swal from "sweetalert2"). These resolve via Importmap; in a pure esbuild/webpack setup with no importmap tag on the page, call window.Swal.fire(...) from your bundle instead.

---

Data attributes

All attributes are read from the element's dataset. Values carry through button_to, link_to, form_with, and raw HTML equally.

Single-step confirm (data-swal-confirm)

Attribute	Accepts	Maps to (SA2 option)
data-swal-confirm	String or JSON object or JSON array	message (String) → text; Object → full SA2 options (overrides all shortcuts); Array → multi-step chain (see below)
data-swal-title	String	title
data-swal-text	String	text
data-swal-icon	String ("warning", "error", …)	icon (default "warning")
data-swal-confirm-text	String	confirmButtonText
data-swal-cancel-text	String	cancelButtonText
data-swal-options	JSON Object (stringified)	Full SA2 options — wins over all shortcuts and over the JSON object form of data-swal-confirm

Merge order (later wins):

defaults → data-swal-* shortcuts → JSON object in data-swal-confirm → data-swal-options

Multi-step chain (data-swal-steps)

Attribute	Accepts	Behavior
data-swal-steps	JSON Array of step Hashes (stringified)	Runs the chain. Per-step defaults { showCancelButton: true, focusCancel: true, icon: "warning" } are merged first and can be overridden key-by-key. Every step is a full SA2 options Hash plus the optional onConfirmed / onDenied sub-chain keys.

Both attributes coexist — if data-swal-steps is present and non-empty, it takes precedence over data-swal-confirm.

Turbo data-turbo-confirm

When confirm_mode is :turbo_override or :both, data-turbo-confirm accepts:

Form	Behavior
String	SA2 popup with the string as text.
Hash (JSON-encoded by Rails)	Full SA2 options.
Array (JSON-encoded by Rails)	Multi-step chain — same shape as data-swal-steps.

---

Stimulus controller reference

Registered under the identifier "swal".

Values

Value	Type	Default	Used by
optionsValue	Object	{}	fire, confirm
stepsValue	Array	[]	chain

Actions

Action	Target behavior
fire	Fires Swal.fire(optionsValue). Calls preventDefault() on the event if the element is <a> or <button>. Returns the SA2 promise.
confirm	Fires Swal.fire({ showCancelButton: true, focusCancel: true, ...optionsValue }). On isConfirmed, calls requestSubmit() (fallback submit()) on the enclosing form.
chain	Runs chainDialogs(Swal, stepsValue). On resolved true, calls requestSubmit() / submit() on the enclosing form. Returns the boolean.

Example:

<button data-controller="swal"
        data-action="click->swal#chain"
        data-swal-steps-value='[{"title":"Sure?"},{"title":"Really?"}]'>
  Proceed
</button>

---

JS runtime

Entry point

import "swal_rails"              // installs confirm + flash handlers

Expected in your JS entrypoint (e.g. app/javascript/application.js).

Re-exports

import Swal from "sweetalert2"                            // SA2, re-exported as default from swal_rails
import { Swal } from "swal_rails"                         // named re-export (same instance)
import { chainDialogs, CHAIN_DEFAULTS } from "swal_rails/chain"
import { installConfirm } from "swal_rails/confirm"       // for custom boot sequences
import { installFlash } from "swal_rails/flash"           // same

chainDialogs(Swal, steps)

chainDialogs(Swal: typeof import("sweetalert2"), steps: Array<StepOptions>): Promise<boolean>

Returns true iff a complete path through the chain was confirmed. steps may be empty (resolves true immediately). Non-array input resolves true as well.

StepOptions is any valid SA2 options Hash, plus the two chain-only keys:

Key	Type	Effect
onConfirmed	Array<StepOptions>	On isConfirmed, run this sub-chain and adopt its boolean result (replaces the remainder of the current chain).
onDenied	Array<StepOptions>	On isDenied (requires showDenyButton: true), run this sub-chain and adopt its boolean result. Without this key, isDenied aborts the chain.

Events

Event name	Target	event.detail	When
swal-rails:ready	document	{ Swal, config }	Fired once per page lifetime after the first successful boot (not per Turbo navigation).

Meta-tag contract

Meta name	Payload	Read by
swal-config	to_client_payload JSON	Runtime boot — mixin, confirm handler, flash handler. Once per page.
swal-flash	Array of { key, options }	Flash runtime — re-read on every turbo:load.

Flash entries are { key: "notice", options: { text: "..." } } for string values, or { key: "notice", options: {...user hash...} } for Hash values. Arrays in flash[key] are expanded into one entry per element.

---

Generators

bin/rails g swal_rails:install

Flag	Type	Default	Values
--mode	String	auto	auto, importmap, jsbundling, sprockets
--confirm_mode	String	data_attribute	off, data_attribute, turbo_override, both — baked into the generated initializer
--skip_layout	Boolean	false	When set, does not inject <%= swal_rails_meta_tags %> into app/views/layouts/application.html.erb

--mode=auto detection order:

1. config/importmap.rb present → importmap
2. package.json present → jsbundling
3. fallback → sprockets

Per-mode side effects:

• importmap: appends pin "sweetalert2", to: "sweetalert2.esm.all.js" and pin "swal_rails", to: "swal_rails/index.js" to config/importmap.rb; appends import "swal_rails" to app/javascript/application.js.
• jsbundling: runs yarn add sweetalert2@<pinned> or npm install sweetalert2@<pinned> (based on the lockfile present); appends import "swal_rails" to app/javascript/application.js.
• sprockets: appends //= link sweetalert2.js and //= link sweetalert2.css to app/assets/config/manifest.js.

All append operations are idempotent — running the generator twice is safe.

bin/rails g swal_rails:locales

No flags. Copies config/locales/swal_rails.en.yml and swal_rails.fr.yml from the gem into your app's config/locales/.

---

Flash value shapes

Value type	Rendered as
String	{ text: value } — safe by default (SA2 renders via text:, no HTML injection).
Hash	Full SA2 options, shadows flash_map[key]. Any SA2 key is accepted (icon, timer, input, html, iconHtml, …).
Array	Expanded into one entry per element. Strings become { text: elem }, Hashes pass through verbatim.
nil / "" / blank?	Skipped.

Key normalization: Hash keys are symbolize_keys-ed before serialization, so flash[:notice] = { "text" => "..." } and flash[:notice] = { text: "..." } are equivalent.

⚠️ Hash overrides bypass the text: safety net. Using html:, iconHtml:, or footer: with untrusted input is an XSS — SweetAlert2 renders those as raw HTML by design. Rule of thumb: if the value is user-controlled, keep the String form.

---

Chain semantics

Single source of truth for every chain-aware entry point (data-swal-steps, data-turbo-confirm with an array, Stimulus chain action, swal_chain_tag, direct chainDialogs call).

Per step:

SA2 result	Behavior
isDismissed (×, Esc, backdrop)	Abort the current chain → false. Outer chain (if this was a sub-chain) also terminates with false.
isConfirmed	If onConfirmed: [...] is defined, run it recursively and replace the remainder of the current chain with its result. Else continue linearly.
isDenied (requires showDenyButton: true)	If onDenied: [...] is defined, run it recursively and adopt its result. Else abort → false.

Return rules:

• An empty or non-array steps input resolves true immediately.
• A chain resolves true iff it ran to completion along a path without any dismiss or unbranched deny.
• Sub-chains inherit the same per-step defaults (showCancelButton: true, focusCancel: true, icon: "warning").
• onConfirmed / onDenied keys are stripped before being passed to Swal.fire, so they never leak into the SA2 popup options.

Callback contract for Turbo override: the chain's final Promise<boolean> is what Turbo.setConfirmMethod receives — false cancels the navigation / form submit, true proceeds.

---

🌍 I18n

Locales en and fr ship with the gem. To copy them into your app for customization:

$ bin/rails g swal_rails:locales

Generated keys:

en:
  swal_rails:
    confirm_button_text: "OK"
    cancel_button_text:  "Cancel"
    deny_button_text:    "No"
    close_button_aria_label: "Close this dialog"

The current I18n.locale is read on every request and injected into the client payload — change languages, button labels follow.

---

♿ Accessibility

• Reduced motion — when prefers-reduced-motion: reduce is set, animations are disabled (showClass/hideClass emptied).
• Focus trap & ARIA — SweetAlert2's built-in focus management and ARIA roles are preserved; returnFocus: true brings focus back to the trigger.
• Translatable labels — all button / aria labels go through I18n.

---

🔒 Security & CSP

XSS safety

All strings flowing through the Ruby helpers are hardened against the usual breakout sequences:

• swal_tag runs the serialized options through ERB::Util.json_escape, which neutralizes </script>, <!--, U+2028 and U+2029 before they reach the inline <script> body.
• swal_config_meta_tag and swal_flash_meta_tag emit <meta> attributes, which Rails HTML-escapes automatically; the JS runtime feeds messages to SweetAlert2's text: option (not html:), so flash payloads are rendered as text even if they contain HTML.

⚠️ Hash-form overrides bypass the text: safety net. When you pass a Hash to flash[key], data-turbo-confirm, data-swal-confirm, or data-swal-options, its keys flow straight into Swal.fire. Using html:, iconHtml:, or footer: with untrusted input is an XSS — SweetAlert2 renders those as raw HTML by design. Rule of thumb: if the value is user-controlled, keep the String form (or the text: key).

Content Security Policy

Meta tags carry no script and need no nonce. For the inline helper:

<%= swal_tag({ title: "Saved" }, nonce: true) %>

When ActionView's CSP helper is available, Rails substitutes the per-request nonce; otherwise nonce: true is silently dropped so the tag stays valid on apps without a configured CSP.

SweetAlert2 + strict style-src — SA2 injects styles via JavaScript. Under style-src 'self' with no 'unsafe-inline', the popups won't be styled. Either ship SA2's CSS via your normal stylesheet (the gem vendors sweetalert2.css) or allow a style nonce for the inserted tags.

---

🎭 Themes

The six official SweetAlert2 themes are vendored alongside the default stylesheet — pick one, load it in your layout, and set the data-swal2-theme attribute to activate it.

Theme	File
Bootstrap 4	sweetalert2/themes/bootstrap-4.css
Bootstrap 5	sweetalert2/themes/bootstrap-5.css
Borderless	sweetalert2/themes/borderless.css
Bulma	sweetalert2/themes/bulma.css
Material UI	sweetalert2/themes/material-ui.css
Minimal	sweetalert2/themes/minimal.css

Importmap / jsbundling (apps that load their own CSS)

<%# app/views/layouts/application.html.erb %>
<%= stylesheet_link_tag "sweetalert2/themes/bootstrap-5" %>
<body data-swal2-theme="bootstrap-5">

Sprockets

/* app/assets/stylesheets/application.css */
*= require sweetalert2/themes/bootstrap-5

bootstrap-5 and material-ui ship both a light and a dark variant baked into the same file — set data-swal2-theme="bootstrap-5-dark" or "material-ui-dark" to opt into dark mode.

OS-driven dark mode? Hook the attribute to prefers-color-scheme with a one-liner:

document.body.dataset.swal2Theme =
  matchMedia("(prefers-color-scheme: dark)").matches
    ? "bootstrap-5-dark" : "bootstrap-5"

---

🎨 Asset pipelines

swal_rails adapts to whichever pipeline you use — the generator picks the right template automatically.

┌─ Importmap (Rails 7+ default) ───────────────────────────────────────┐
│   config/importmap.rb                                                │
│     pin "sweetalert2", to: "sweetalert2.js"                          │
│     pin "swal_rails",  to: "swal_rails.js"                           │
│   app/javascript/application.js                                      │
│     import "swal_rails"                                              │
└──────────────────────────────────────────────────────────────────────┘

┌─ jsbundling (esbuild / vite / rollup) ───────────────────────────────┐
│   package.json  →  "sweetalert2": "^11"  (your bundler resolves it)  │
│   app/javascript/application.js                                      │
│     import "swal_rails"                                              │
└──────────────────────────────────────────────────────────────────────┘

┌─ Sprockets (legacy) ─────────────────────────────────────────────────┐
│   app/assets/javascripts/application.js                              │
│     //= require sweetalert2                                          │
│     //= require swal_rails                                           │
└──────────────────────────────────────────────────────────────────────┘

---

🧪 Development

$ git clone https://github.com/Metalzoid/swal_rails.git
$ cd swal_rails
$ bundle install
$ bundle exec rspec         # 47 examples, real headless Chromium (Cuprite)
$ bundle exec rubocop       # style

Test against a specific Rails version:

$ bundle exec appraisal install
$ BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile bundle exec rspec
$ BUNDLE_GEMFILE=gemfiles/rails_8_1_sprockets.gemfile bundle exec rspec

Repo layout

swal_rails/
├── app/                           # Engine: helpers, views, assets
├── lib/
│   ├── swal_rails.rb              # entrypoint + Engine + Railtie
│   ├── swal_rails/configuration.rb
│   └── generators/
│       ├── install/               # bin/rails g swal_rails:install
│       └── locales/               # bin/rails g swal_rails:locales
├── vendor/javascript/sweetalert2/ # pinned SA2 v11.26.24 (MIT)
├── spec/
│   └── dummy/                     # minimal Rails app for system tests
├── Appraisals                     # Rails 7.2 → 8.1 + sprockets variant
└── gemfiles/                      # per-version lockfiles (generated)

---

🤝 Contributing

Bug reports and pull requests welcome on GitHub at https://github.com/Metalzoid/swal_rails.

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Make sure tests and RuboCop pass (bundle exec rspec && bundle exec rubocop)
4. Push (git push origin my-new-feature)
5. Open a Pull Request

---

🙏 Credits & license

This gem bundles SweetAlert2 by Tristan Edwards, Limon Monte and contributors, distributed under the MIT License. The full license is included at vendor/javascript/sweetalert2/LICENSE.

swal_rails itself is released under the MIT License.

Built with 🍬 by [Metalzoid](https://github.com/Metalzoid)