lucide-icons

Lucide Icons in Rails

Render Lucide icons as inline SVGs via the lucide-rails gem. Icons use currentColor so they inherit text color automatically.

When To Use This Skill

• Adding icons to a Rails view (buttons, nav, badges, empty states)
• Choosing the right Lucide icon name for a UI element
• Making icons accessible (decorative vs interactive)
• Styling or sizing SVG icons with CSS

Philosophy

1. Icons are decoration until they aren't — Decorative icons need no label. Interactive icons (buttons, links) MUST have accessible text.
2. Size intentionally — Always pass size:. The default 24px is too large for most inline contexts.
3. Let CSS handle color — Icons inherit currentColor. Style the parent, not the SVG.
4. Use the helper, never raw SVGs — lucide_icon keeps icons consistent, cacheable, and updatable.
5. kebab-case names only — It's "chevron-right", never "chevronRight" or "ChevronRight".

Installation

# Gemfile
gem "lucide-rails"

bundle install

No JavaScript, no import maps, no asset pipeline config. The gem provides a Ruby helper that renders inline SVGs.

Basic Usage

<%= lucide_icon "home", size: 18 %>

Renders:

Helper Parameters

Any additional HTML attributes are passed through to the <svg> element:

Size Guidelines

Pick size based on context. Be consistent within each context.

Styling with CSS

Color Inheritance

Icons stroke with currentColor — they inherit the parent's color:

Direct Icon Styling

When you need icon-specific colors, use a utility class on the parent or icon wrapper:

Stroke Width

Thinner strokes look more refined at larger sizes. Thicker strokes read better small.

Dark Mode

Since icons use currentColor, they adapt to dark mode when your text colors do. No extra work needed if your color system uses CSS custom properties.

Common Patterns

Icon + Text Button

Icon-Only Button

Icon-only buttons MUST have aria-label.

Navigation Link

Badge with Icon

Empty State

Icon in Link (Turbo)

Stimulus Integration

Accessibility

Rule: Decorative vs. Meaningful

Decorative — icon accompanies visible text. No extra markup needed:

Meaningful — icon is the only content. MUST add accessible text:

Screen Reader Only Class

SVGs Are aria-hidden by Default

The lucide_icon helper renders SVGs that screen readers skip. This is correct — the accessible name belongs on the interactive parent element, not the icon.

Common Icons by Use Case

Navigation

Actions

Arrows & Chevrons

Status & Feedback

Communication

Files & Content

Social & Misc

Anti-Patterns

1. Wrong icon name casing — "chevronRight" → use "chevron-right" (kebab-case always)
2. Missing size — Don't rely on default 24px. Be explicit: size: 16
3. Raw <svg> or <img> tags — Always use lucide_icon helper
4. Styling SVG directly — Style the parent element's color, not the SVG's stroke
5. Icon-only button without aria-label — Screen readers can't describe it
6. Inconsistent sizes — Pick a size per context and stick to it
7. Too many different icons — Reuse the same icon for the same concept across your app
8. Using icons without visible text when meaning is ambiguous — A pencil icon might mean "edit" or "write." Add text or a tooltip.

Finding Icons

Browse the full library at lucide.dev/icons.

Search tips:

• Search by concept: "arrow", "file", "user", "check"
• Icons are named descriptively: circle-check not checkmark-in-circle
• Related icons share prefixes: file, file-text, file-plus, file-x
• If an icon doesn't exist in lucide-rails, the helper will raise an error at render time

Reference

For detailed patterns, edge cases, and advanced usage, see reference.md.