Icons

Icons come from lucide-rails, the Rails port of Lucide, which is the icon set shadcn/ui uses. ui_icon wraps lucide_icon and adds shadcn's sizes.

The application needs the lucide-rails gem. shadwire init adds it, and bin/shadwire status --json lists it under gems.

Names are Lucide's, in kebab-case

<%# Wrong: React component names do not exist here %>
<%= ui_icon("ChevronDown") %>
<%= ui_icon(:chevron_down) %>

<%# Right %>
<%= ui_icon("chevron-down") %>

You can browse the names at lucide.dev/icons.

Sizes

Size	Class	Typical use
`:sm`	`size-3`	Inside badges, supporting text and breadcrumbs.
`:default`	`size-4`	Buttons, menu items, fields.
`:lg`	`size-5`	Headings, tiles, empty states.
`:xl`	`size-6`	Illustrations and feature callouts.

<%= ui_icon("check", size: :sm) %>

Use these sizes rather than class: "w-3 h-3", so your icons change along with everything else if the scale is ever adjusted.

Icons are decorative by default

ui_icon renders aria-hidden="true". That is what you want next to a text label, because the text already names the control.

<%# Right: "Download" is already the label; the icon is decoration %>
<%= ui_button { safe_join([ ui_icon("download"), " Download" ]) } %>

When the icon is the only content, it has to provide the name. Pass label:, which sets role="img" and aria-label and drops the aria-hidden:

<%# Wrong: icon-only button with no accessible name %>
<%= ui_button(size: :icon) { ui_icon("trash-2") } %>

<%# Right: either of these works %>
<%= ui_button(size: :icon) { ui_icon("trash-2", label: "Delete") } %>
<%= ui_button(size: :icon, "aria-label": "Delete") { ui_icon("trash-2") } %>

Putting the label on the button instead of the icon works just as well. What doesn't work is leaving both without one.

There is no icon: prop

No component takes an icon as an argument. As in shadcn/ui, you put the icon in the content.

<%# Wrong: no component has that prop %>
<%= ui_button(icon: "plus") { "Adicionar" } %>

<%# Right %>
<%= ui_button { safe_join([ ui_icon("plus"), " Adicionar" ]) } %>

ButtonComponent has [&_svg] utilities that size and space a nested icon, so it needs no extra class. Use size: :icon for a button with only an icon.

Join the icon and the text with safe_join rather than building a string. ui_icon("save") + " Save" also works, because the icon is already HTML-safe, but safe_join makes the intent clear and escapes interpolated text properly.