Icons

By default, icons are displayed with the size-5 Tailwind class to set the width and height. This can be overridden without using the ! Tailwind modifier because we utilize the :where() pseudo-class to ensure that our default classes have the lowest CSS specificity possible.

The icon color inherits the text color of the parent element.

You can pass the icon as the first positional argument or via the icon: keyword argument.

Heroicons ships four variants. Append the variant to the icon token — name/variant (outline is the default); other libraries expose their own variants / weights the same way (e.g. phosphor:heart/duotone).

You can customize the size, color, and other properties of the icons using standard Tailwind classes.

To use a library beyond the curated bundled set, sync it into your app once and name it in the icon token as library:name:

bin/rails loco_motion:icons:add lucide phosphor

= loco_icon("lucide:heart")
= loco_icon("phosphor:heart/duotone")

The renderer checks your app's app/assets/svg/icons first, then falls back to the bundled icons — so synced libraries just work.

Duotone icons have two independently colorable layers: the outline strokes with currentColor, so text-* classes color it, while the tint layer inherits the SVG fill, so fill-* classes color it.

Prefer a different library by default? Set it once in an initializer (and pick a matching variant, or nil for a flat library):

# config/initializers/loco_motion.rb
LocoMotion.configure do |config|
  config.default_icon_library = :lucide
  config.default_icon_variant = :outline
end