Rails Toastify

About the project

Rails Toastify is an open-source gem for displaying notifications in Rails applications, inspired by the React Toastify experience. It turns flash messages into notifications with themes, animations, a progress bar and drag-to-dismiss support.

Integration uses view helpers and a configuration file, with no additional application JavaScript required to display flash messages.

Problem

Rails applications need to tell users when an action succeeds or an error occurs. The framework provides the flash mechanism, but each project is responsible for how those messages appear.

Building that presentation involves defining the component, styling, display duration and behavior during navigation. Implementing a separate solution in each application repeats the same work and creates more code to maintain.

Libraries such as React Toastify demonstrate the value of reusable notifications. My goal was to provide a similar experience that follows Rails conventions, with simple configuration and no need to add a JavaScript framework solely for this feature.

Solution

The gem uses a Rails Engine to distribute CSS and JavaScript ready for the asset pipeline. Two view helpers connect those assets to the application’s messages.

After installing the gem and adding the helpers to the layout, the application continues using flash[:notice] and flash[:alert].

gem "rails_toastify"

<%= rails_toastify_container %>
<%= rails_toastify_messages %>

Themes, message types and behavior can be adjusted through the configuration file or individual calls.

My role

I created and maintain the gem. I developed the engine architecture, CSS animations and themes, dependency-free JavaScript layer and configuration API. I also maintain the documentation, compatibility test matrix and RubyGems releases.

Key features

• Automatic notifications from Rails flash messages
• Six screen positions
• Four entrance animations: bounce, slide, flip and zoom
• Three themes: light, dark and colored
• Five message types: default, success, warning, error and info
• Progress bar color configurable per application, message type or notification
• Drag-to-dismiss support with a configurable distance
• JavaScript API for displaying notifications programmatically
• Independent theme, type and duration settings for notice and alert

Architecture and technical decisions

The Rails Engine ships browser-ready CSS and JavaScript, without an additional build step or Node.js dependency. This supports integration with projects using either Propshaft or Sprockets.

The helper serializes flash messages as escaped JSON without injecting inline scripts. The gem’s JavaScript reads that content on DOMContentLoaded and turbo:load, and also handles pages that have already loaded. This supports both traditional and Turbo navigation.

Configuration follows a defined order of precedence: call options, message type options, global configuration and theme defaults. Applications can set a shared behavior while customizing individual notifications when needed.

Drag-to-dismiss uses Pointer Events, sharing the implementation across mouse, touch and pen input.

Declared compatibility covers Ruby 3.2 or later and Rails 7.1 through 8. These combinations are checked in a test matrix before each release. Configuration values from earlier versions are accepted and normalized to preserve compatibility during upgrades.

Outcome

Published on RubyGems under the MIT license, with more than 6,000 downloads and production use. Projects using the gem include a municipal government website in Pará, Brazil, Meus Compromissos and Medicare.

Technologies

Ruby, Ruby on Rails, JavaScript, CSS, Turbo and RubyGems.