Getting started

List the icon sets this generator knows about:

npx elm-icons list

Supported icon sets:

heroicons-outline
heroicons-solid
lucide
phosphor-bold
phosphor-duotone
phosphor-fill
phosphor-light
phosphor-regular
phosphor-thin

Generate an icon module with install <icon-set>. In this project, install means "generate Elm code" rather than installing a package. Generated modules are written under src/Ui/Icons/ by default.

npx elm-icons install lucide
npx elm-icons install heroicons-outline
npx elm-icons install phosphor-regular

Use --subset to generate only the icons you want:

npx elm-icons install lucide --subset house,search,settings

Use the module's view function to render an icon:

import Html exposing (Html)
import Ui.Icons.Lucide as Lucide


viewSearch : Html msg
viewSearch =
    Lucide.view Lucide.search

Icons inherit size and color from the surrounding tree. The generated SVG uses width="1em", height="1em", and currentColor.

Html.span
    [ Html.Attributes.style "font-size" "20px"
    , Html.Attributes.style "color" "rebeccapurple"
    ]
    [ Lucide.view Lucide.search ]

Sprite Mode

By default, each generated Elm icon contains its own SVG nodes. Sprite mode writes one SVG sprite file and generates Elm icons that reference symbols from that file.

npx elm-icons install lucide \
  --subset house,search,settings \
  --as-sprites public/assets/lucide.svg

That generates Elm like this:

type Icon msg
    = Icon (Html.Html msg)


view : Icon msg -> Html.Html msg
view (Icon html) =
    html


search : Icon msg
search =
    icon "/assets/lucide.svg#search"

Use --sprite-url when the URL in the generated <use href="..."> needs to be different from the file path you write locally:

npx elm-icons install lucide \
  --as-sprites generated/assets/lucide.svg \
  --sprite-url /static/icons/lucide.svg

Stroke-based sprite sets, such as lucide and heroicons-outline, use the CSS custom property --icon-stroke-width so you can adjust stroke width at the call site.

Html.span
    [ Html.Attributes.style "--icon-stroke-width" "1.75" ]
    [ Lucide.view Lucide.search ]

Icon Adapters

Each generated module exposes an Icon msg type plus a view function. That lets your app pass icons around as data and decide how to render them in one place.

For plain Html, use the generated view directly:

Lucide.view Lucide.search

For Elm UI, wrap the generated HTML in your own adapter:

import Element exposing (Element)
import Ui.Icons.Lucide as Lucide


icon : Lucide.Icon msg -> Element msg
icon value =
    Element.html (Lucide.view value)

Then use icons in Elm UI code without exposing the generated rendering details:

Element.row []
    [ icon Lucide.search
    , Element.text "Search"
    ]

Options

Generate only the icons you use with --subset. Names are the source SVG names, comma-delimited:

npx elm-icons install heroicons-outline --subset home,magnifying-glass,cog-6-tooth
npx elm-icons install phosphor-regular --subset house,magnifying-glass,gear

Write generated Elm modules somewhere other than src with --output-dir:

npx elm-icons install lucide --output-dir generated

Generated icons are decorative by default with aria-hidden="true" and focusable="false". Put accessible labels on the containing control, such as a button label.