stimulus-plumbers-tailwind
Tailwind CSS v4 theme for stimulus_plumbers. Extends the base theme with utility classes for all components.
Requirements
- Ruby >= 3.0
stimulus_plumbers>= 0.2.9- Tailwind CSS v4 in your build toolchain
Installation
# Gemfile
gem "stimulus_plumbers_tailwind"
bundle install
Activate the theme in an initializer or config/application.rb:
StimulusPlumbers.configure do |config|
config.theme = :tailwind
end
Tell Tailwind to scan the gem's lib files so component class names are included in the generated CSS. Add an @source directive pointing at the gem's installed path:
@import "tailwindcss";
@source "/path/to/gems/stimulus_plumbers_tailwind-VERSION/lib/**/*.rb";
Use bundle show stimulus_plumbers_tailwind to get the exact installed path.
Theming
StimulusPlumbers::Themes::TailwindTheme subclasses StimulusPlumbers::Themes::Base and provides CSS class resolution for all component families:
| Module | Components |
|---|---|
Tailwind::ActionList |
Action list, menu items |
Tailwind::Avatar |
Avatar |
Tailwind::Button |
Button |
Tailwind::Calendar |
Calendar grid, date picker |
Tailwind::Card |
Card |
Tailwind::Combobox |
Combobox (date, time, dropdown, typeahead) |
Tailwind::Form |
Form fields, labels, errors |
Tailwind::Icon |
Icon (SVG rendering, icon registry) |
Tailwind::Layout |
Layout primitives |
Custom themes can subclass TailwindTheme to override individual methods, or subclass StimulusPlumbers::Themes::Base directly.
Icons
The theme bundles the Heroicons 2.x set. Pass a kebab-case icon name to sp_icon or any component accepting icon_leading: / icon_trailing:. Append /solid for the filled variant:
<%= sp_icon "arrow-left" %>
<%= sp_icon "arrow-left/solid" %>
<%= sp_button "Next", icon_trailing: "arrow-right" %>
Icons render as inline <svg> with size-6 by default. Override with class::
<%= sp_icon "arrow-left", class: "size-4 text-gray-500" %>
Built-in aliases: "close" → "x-mark", "calendar" → "calendar-days".
Optional heroicons gem: add gem "heroicons" to your Gemfile to load icons from the gem instead of the bundled files. The theme detects it automatically.
Development
bundle install
npm install
bundle exec rake test:unit # unit tests
npm run test:snapshots # visual snapshot tests (Playwright)
npm run test:snapshots:update # regenerate baseline screenshots
bundle exec rake rubocop # lint
bundle exec rake coverage # run tests with coverage + collate report
The sandbox Rails app lives in test/sandbox/. Run it with:
bundle exec puma test/sandbox/config.ru