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.

LocoMotion bundles only Heroicons to keep the gem small. To use another library, sync it into your app once and name it in the icon token as library:name:

bash bin/rails loco_motion:icons:add lucide phosphor

haml = 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.

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

ruby LocoMotion.configure do |config| config.default_icon_library = :lucide config.default_icon_variant = nil end