Message Block

Implements the common view pattern by which a list of messages are shown at the top of a page, often a combination of flash messages and validation errors on one or more models. One helper call renders a styled block of messages grouped by type (error, confirmation, warning, etc.).

• Rails 6.1 or newer
• Ruby 2.7 or newer

For older Rails versions, use message_block 2.x.

Add the gem to your Gemfile:

gem "message_block", "~> 3.0"

The gem ships an optional stylesheet. With Propshaft (the Rails 8 default), link it in your layout:

<%= stylesheet_link_tag "message_block" %>

With Sprockets, require it from application.css:

/*
 *= require message_block
 */

If you use Tailwind, Bootstrap or another CSS framework, you can skip the stylesheet and style the generated markup yourself.

Call the message_block helper in a view or layout:

<%= message_block on: [:user, :comment] %>

Given these flash messages in the controller:

class CommentsController < ApplicationController
  def create
    flash.now[:error] = "Error A"
    flash.now[:confirm] = "Confirmation A"   # Use whichever types you like
    flash.now[:warn] = ["Warn A", "Warn B"]  # Arrays show multiple messages
  end
end

and given that both @user and @comment fail validation, the helper renders:

<div id="message_block" class="message_block" role="alert">
  <ul class="confirm">
    <li>Confirmation A</li>
  </ul>
  <ul class="error">
    <li>Error A</li>
    <li>User first name can't be blank</li>
    <li>Comment contents can't be blank</li>
  </ul>
  <ul class="warn">
    <li>Warn A</li>
    <li>Warn B</li>
  </ul>
</div>

Nothing is rendered when there are no messages.

Messages are HTML-escaped, like any other string you output in a Rails view. Messages that are already html_safe are rendered as they are:

flash.now[:notice] = helpers.link_to("View your order", order_path(@order))

Strings put in the flash before a redirect are stored in the session, and whether they stay html_safe depends on how the session is serialized. With the JSON cookie serializer (the default for apps on load_defaults 7.0 or newer), they come back as plain strings and are escaped. With the older Marshal serializer, they stay html_safe and render as HTML. If your app relies on HTML in flash messages across redirects and its session is serialized as JSON, pass escape: false. Only do this if no message can contain user input, since it renders every message as raw HTML.

To update messages from a Turbo Stream response, render an empty container in your layout so there is always a target:

<%= message_block render_empty: true %>

Then update its contents from the stream:

<%# app/views/comments/create.turbo_stream.erb %>
<%= turbo_stream.update "message_block" do %>
  <%= message_block on: :comment, container: false %>
<% end %>

Set flash messages with flash.now in actions that respond with a Turbo Stream. Because the container keeps role="alert", screen readers announce the new messages.

The bundled stylesheet styles the error, alert, warn, notice, info, confirm and back types. Any other type gets a neutral style. Each type sets CSS custom properties that you can override:

.message_block ul.error {
  --message-block-text: #7f1d1d;
  --message-block-background: #fef2f2;
  --message-block-border: #fecaca;
  --message-block-accent: #dc2626; /* icon color */
}

• Rails 6.1+ and Ruby 2.7+ are required.
• Messages are now HTML-escaped. Messages marked html_safe still render as HTML. Pass escape: false to keep the 2.x behavior; see HTML in messages.
• The container has role="alert" by default. Pass html: { role: nil } to remove it.
• The :html option is merged with the default id and class instead of replacing them.
• The stylesheet has been rewritten as plain CSS with inline SVG icons, and the message_block/*.gif images have been removed.

Run the specs against the current Rails version:

bundle install
bundle exec rspec

Run them against every supported Rails version with Appraisal:

bundle exec appraisal install
bundle exec appraisal rspec

Released under the MIT license. See LICENSE.