Icons
Rails UI includes the railsui_icon gem for easy icon integration. The gem provides a simple helper method to render SVG icons in your views.
Icons are based on Heroicons, the popular icon set from the makers of Tailwind CSS.
Basic Usage
Use the icon helper to render icons in your views:
<%= icon "check" %>
<%= icon "x-mark" %>
<%= icon "arrow-right" %>
<%= icon "user" %>
Icon names match Heroicons naming conventions. Use kebab-case for multi-word icons.
Styling Icons
Add CSS classes to customize size, color, and other properties:
<!-- Size with Tailwind classes -->
<%= icon "check", class: "size-4" %>
<%= icon "check", class: "size-6" %>
<%= icon "check", class: "size-8" %>
<%= icon "check", class: "w-12 h-12" %>
<!-- Colors -->
<%= icon "check", class: "size-5 text-green-500" %>
<%= icon "x-mark", class: "size-5 text-red-500" %>
<%= icon "exclamation-triangle", class: "size-5 text-yellow-500" %>
<!-- Stroke width (for outline icons) -->
<%= icon "check", class: "size-5 stroke-2" %>
<!-- Fill for solid icons -->
<%= icon "heart", class: "size-5 fill-red-500", variant: :solid %>
Icon Variants
Heroicons come in three variants. Specify the variant with the variant option:
<!-- Outline (default) - 24x24, stroke-based -->
<%= icon "heart", class: "size-6" %>
<!-- Solid - 24x24, filled -->
<%= icon "heart", class: "size-6", variant: :solid %>
<!-- Mini - 20x20, filled, optimized for smaller sizes -->
<%= icon "heart", class: "size-5", variant: :mini %>
<!-- Micro - 16x16, filled, for tight spaces -->
<%= icon "heart", class: "size-4", variant: :micro %>
When to use each variant
- Outline (default): Best for most UI elements, buttons, and navigation
- Solid: Use for filled states, active indicators, or higher visual weight
- Mini: Optimized for 20px, good for form elements and tight spaces
- Micro: 16px icons for badges, tags, and inline text
Custom Icons
You can also render custom SVG icons from your assets using the custom_path option:
<!-- Custom SVG from public folder -->
<%= icon "logo", custom_path: "/logo.svg", class: "w-8 h-auto" %>
<!-- Social icons -->
<%= icon "github", custom_path: "/social/github.svg", class: "size-5 fill-current" %>
<%= icon "twitter", custom_path: "/social/x.svg", class: "size-5 fill-current" %>
<!-- Brand icons -->
<%= icon "railsui-logo", custom_path: "/railsui-logo.svg", class: "w-24 h-auto fill-current" %>
Custom icons should be placed in your public folder or served from your asset pipeline.
Common Patterns
Buttons with icons
<%= link_to some_path, class: "btn btn-primary inline-flex items-center gap-2" do %>
<%= icon "plus", class: "size-4" %>
<span>Add Item</span>
<% end %>
<%= button_tag class: "btn btn-white inline-flex items-center gap-2" do %>
<span>Download</span>
<%= icon "arrow-down-tray", class: "size-4" %>
<% end %>
Icon-only buttons
<%= button_tag class: "p-2 rounded-lg hover:bg-neutral-100", title: "Settings" do %>
<%= icon "cog-6-tooth", class: "size-5 text-neutral-600" %>
<span class="sr-only">Settings</span>
<% end %>
Status indicators
<div class="flex items-center gap-2">
<%= icon "check-circle", class: "size-5 text-green-500", variant: :solid %>
<span>Completed</span>
</div>
<div class="flex items-center gap-2">
<%= icon "clock", class: "size-5 text-yellow-500" %>
<span>Pending</span>
</div>
<div class="flex items-center gap-2">
<%= icon "x-circle", class: "size-5 text-red-500", variant: :solid %>
<span>Failed</span>
</div>
Navigation items
<%= link_to dashboard_path, class: "flex items-center gap-3 px-3 py-2 rounded-lg hover:bg-neutral-100" do %>
<%= icon "home", class: "size-5 text-neutral-500" %>
<span>Dashboard</span>
<% end %>
<%= link_to settings_path, class: "flex items-center gap-3 px-3 py-2 rounded-lg hover:bg-neutral-100" do %>
<%= icon "cog-6-tooth", class: "size-5 text-neutral-500" %>
<span>Settings</span>
<% end %>
Form feedback
<!-- Success message -->
<div class="flex items-center gap-2 p-3 bg-green-50 text-green-800 rounded-lg">
<%= icon "check-circle", class: "size-5", variant: :solid %>
<span>Your changes have been saved.</span>
</div>
<!-- Error message -->
<div class="flex items-center gap-2 p-3 bg-red-50 text-red-800 rounded-lg">
<%= icon "exclamation-circle", class: "size-5", variant: :solid %>
<span>Please fix the errors below.</span>
</div>
Available Icons
Rails UI includes the full Heroicons set. Browse all available icons at heroicons.com.
Common icons you'll use frequently:
Accessibility
Icons are decorative by default and include aria-hidden="true". For icon-only buttons, always include screen reader text:
<%= button_tag class: "p-2 rounded-lg hover:bg-neutral-100" do %>
<%= icon "trash", class: "size-5 text-red-500" %>
<span class="sr-only">Delete item</span>
<% end %>
The sr-only class (included with Tailwind) hides the text visually while keeping it accessible to screen readers.
