Beautiful toast notifications for Ruby on Rails 8 using Stimulus and plain CSS.
Sileo Rails is inspired by and adapts ideas from the original project by Aryan: hiaaryan/sileo.
- Rails 8 engine with helper + controller methods
- Stimulus toaster controller
- Global JavaScript API (
window.Sileo) - API parity with Sileo docs:
show, typed states,promise,dismiss,clear - Toast options:
position,duration,fill,roundness,autopilot,styles,icon,button show()generic toast mode (no state badge by default)- No animation libraries and no frontend framework dependency
- Works from server-side and JavaScript
- Ruby
>= 3.2 - Rails
>= 8.0 - Propshaft + Importmap setup (default in new Rails 8 apps)
Add the gem to your app:
# Gemfile
gem "sileo-rails"Install dependencies and run the installer:
bundle install
bin/rails g sileo:installThe installer does the following:
- Adds importmap pins for Sileo JS modules
- Imports Sileo in
app/javascript/application.js - Registers the Sileo Stimulus controller in
app/javascript/controllers/application.js - Creates
config/initializers/sileo.rb(unless skipped) - Adds
app/views/application/_sileo_toaster.html.erb
In your layout (app/views/layouts/application.html.erb), render the toaster:
<body>
<%= render "application/sileo_toaster" %>
<%= yield %>
</body>If you prefer linking CSS manually in the layout with Propshaft, use:
<%= stylesheet_link_tag "sileo", "data-turbo-track": "reload" %>- Add
gem "sileo-rails"to the appGemfile - Run
bundle install - Run
bin/rails g sileo:install - Add
<%= render "application/sileo_toaster" %>to the application layout body - Restart the Rails server
- Trigger a toast from a controller or browser console
Controller example:
class PostsController < ApplicationController
def create
if Post.create(post_params)
sileo_success "Post created"
redirect_to posts_path
else
sileo_error "Could not create post", description: "Please review the form"
render :new, status: :unprocessable_entity
end
end
endJavaScript example:
window.Sileo.success("Saved")
window.Sileo.error({ title: "Error", description: "Try again" })<%= sileo_toaster position: :top_right, offset: 16 %>With default options for all toasts in this toaster:
<%= sileo_toaster(
position: :bottom_right,
options: {
duration: 7000,
roundness: 20,
autopilot: { expand: 120, collapse: 4500 }
}
) %>window.Sileo.success("Saved")
window.Sileo.error({ title: "Error", description: "Try again" })
window.Sileo.show({ title: "Generic message", description: "No default state icon" })
window.Sileo.promise(fetch("/health"), {
loading: { title: "Checking..." },
success: { title: "Service is up" },
action: (response) => ({ title: "Service is up", button: { title: "Open", action: "open_service" } }),
error: { title: "Service unavailable" }
})window.dispatchEvent(new CustomEvent("sileo:show", {
detail: { title: "Event based toast", state: "info" }
}))title(String)description(String)state(success,error,warning,info,loading,action)position(top-left,top-center,top-right,bottom-left,bottom-center,bottom-right)duration(Integerms ornull)fill(Stringcolor)titleColor(Stringcolor for title text)iconColor(Stringcolor for icon)roundness(Integerpx)button({ title: String, action: String })autopilot(Booleanor{ expand: Integer, collapse: Integer })
Ruby controller options also accept title_color: and icon_color:.
Create or edit config/initializers/sileo.rb:
Sileo.configure do |config|
config.default_position = :top_right
config.default_duration = 6000
config.default_roundness = 18
config.default_offset = 16
config.enable_autopilot = true
config.autopilot_expand_delay = 150
config.autopilot_collapse_delay = 4000
endA full Rails demo app is included in this repository under demo/rails.
cd demo/rails
bundle install
bin/rails db:prepare
bin/devOpen http://127.0.0.1:3000.
For additional troubleshooting and environment notes, see:
demo/rails/README.md.
bundle install
bundle exec rspecFor full contributor and release workflow details, see:
DEVELOPMENT.md.
- Create a branch from
main - Add or update specs for behavior changes
- Run
bundle exec rspec - Update docs/changelog when user-facing behavior changes
- Open a pull request describing the change and verification steps
Please keep pull requests focused and include reproducible steps for bug fixes.
This project is licensed under the MIT License. See LICENSE.txt.