# `LedgerUI.Components.Icon`
[🔗](https://github.com/devaction-labs/ledger_ui/blob/v0.2.0/lib/ledger_ui/components/icon.ex#L1)

Server-side SVG icons (Hugeicons Stroke Rounded), no JavaScript needed.

    <.icon name="download" />
    <.icon name="huge-download-01" size="sm" class="muted" />
    <.icon name="check-circle" boxed tone="success" />

The output is identical to what `LedgerUI.hydrate()` produces from `<i data-i="name">`:

    <svg class="lu-i sm" viewBox="0 0 24 24" aria-hidden="true" data-icon="download">...</svg>

Every icon is precomputed at compile time from `priv/icons.json` (regenerate it with
`elixir scripts/extract_icons.exs`) as an iodata binary and emitted with `Phoenix.HTML.raw/1`,
so rendering costs one map lookup.

## Names

Dictionary keys (`download`, `chevron-down`, ...) are used as-is. The API's `huge-*` names
are accepted too: `huge-` (or `hugeicons:`) is stripped, then the exact key is tried, then
the key without a trailing `-NN` suffix (`huge-download-01` -> `download-01` -> `download`).
Unknown names render nothing and log a warning (disable with
`config :ledger_ui, warn_unknown_icons: false`).

## Vendored icons

Icons outside the dictionary come from the app's own folder, filled by `mix ledger_ui.icons`
(`get`, `sync`; see `LedgerUI.Icons`):

    config :ledger_ui, :icons_path, "priv/hugeicons"

    <.icon name="huge-invoice-01" />

They are loaded once into `:persistent_term` and render the same markup as the built-in ones.
Order of lookup: a built-in key (exact, after dropping `huge-`), then a vendored file of that
name, then the built-in key without its `-NN` suffix. So a built-in name always wins over a
vendored file of the same name, while `huge-download-01` finds the vendored `download-01.svg`
before settling for the built-in `download`.

## Box

`boxed` wraps the icon in the `lu-ic` box; `tone` colours it (`accent`/`acc`, `success`/`pos`,
`error`/`neg`, `warning`/`warn`, `info`, `lime`, `neutral`). `box_size="lg"` gives the large
box; any number of pixels sets width/height inline. The inner block replaces `name`.

# `builtin?`

```elixir
@spec builtin?(String.t()) :: boolean()
```

Whether `name` (with or without `huge-`) is a key of the built-in dictionary.

`mix ledger_ui.icons sync` skips these: they need no download.

# `icon`

## Attributes

* `name` (`:string`) - Icon name (dictionary key or `huge-*`). Defaults to `nil`.
* `size` (`:string`) - Defaults to `nil`.Must be one of `nil`, `"sm"`, `"md"`, `"lg"`, or `"xl"`.
* `class` (`:any`) - Defaults to `nil`.
* `boxed` (`:boolean`) - Wraps the icon in the `lu-ic` box. Defaults to `false`.
* `tone` (`:string`) - Box colour (needs `boxed`). Defaults to `nil`. Must be one of `nil`, `"acc"`, `"accent"`, `"error"`, `"info"`, `"lime"`, `"neg"`, `"neutral"`, `"pos"`, `"success"`, `"warn"`, or `"warning"`.
* `box_size` (`:any`) - `"lg"` or a size in pixels. Defaults to `nil`.
* `box_class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block` - Own SVG inside the box, instead of `name`.

# `names`

Names of all icons in the built-in dictionary.

# `resolve`

```elixir
@spec resolve(String.t() | nil) :: String.t() | nil
```

Resolves an API name to a dictionary key (see module docs), or `nil`.

    iex> LedgerUI.Components.Icon.resolve("huge-download-01")
    "download"
    iex> LedgerUI.Components.Icon.resolve("nope")
    nil

---

*Consult [api-reference.md](api-reference.md) for complete listing*
