Lucide
poetry-lucide is the default Poetry icon set: 1,745 Lucide icons vendored into the gem at a pinned upstream commit and sanitized at vendor time, so rendering never parses, never sanitizes, and never touches the network.
Install
Requiring the gem is the setup: it registers the set with the icon
registry as :lucide, and the
Icon component finds it as
the default library with no further wiring. The
install guide already includes it
in the starting Gemfile.
gem "poetry-lucide"
<%= poetry_icon(name: :"circle-check") %>
<%= poetry_icon(name: :search, label: "Search") %>
<%= poetry_icon(name: :plus, class: "size-4 text-muted-foreground") %>
An icon is decorative by default (aria-hidden); pass
label: when it stands alone and it renders as
role="img" with that accessible name. Icons ship
Lucide's intrinsic 24px box and draw their stroke in
currentColor, so they inherit the surrounding text
color; inside Poetry components the component's own sizing rules
take over, and anywhere else class: utilities size
them.
Names, misses, and the fallback
Names are kebab-case symbols, one per vendored file.
poetry check validates icon-name literals statically
against the set, so a misspelled literal is caught before it can
reach a render. A dynamic name (a database value, a user setting)
only surfaces at render: in development and test it raises with a
did-you-mean, and in production the configured fallback renders
instead while the optional on_missing_icon callable
fires. The default fallback is :"circle-question-mark",
which this set ships.
# config/initializers/poetry.rb (defaults shown)
Poetry::Core::Config.current.icon_library = :lucide
Poetry::Core::Config.current.icon_fallback = :"circle-question-mark"
Poetry::Core::Config.current.on_missing_icon =
->(name:, library:, error:) { Rails.logger.warn("missing icon #{name}") }
The pin
The icons vendor from a single upstream commit, never a mutable tag, and the SHA ships in the gem:
Poetry::Lucide.vendored_commit # the upstream commit the icons ship from
Each vendored file holds an icon's sanitized inner markup; the Icon
component owns the svg wrapper and the ARIA contract
riding on it. Sanitization runs once at vendor time, so the render
path trusts the files by construction. The vendored Lucide icons
remain under Lucide's ISC license; LICENSE-LUCIDE.txt
ships in the gem beside them.