ExIconify (ExIconify v0.1.0)

Iconify icons for Elixir and Phoenix applications.

ExIconify provides access to 200,000+ icons from 100+ icon sets including Lucide, Material Design Icons, Tabler, Phosphor, Heroicons, and more.

Installation

Add ex_iconify to your list of dependencies in mix.exs:

def deps do
  [
    {:ex_iconify, "~> 0.1.0"},
    {:req, "~> 0.5"}  # Optional but recommended HTTP client
  ]
end

Quick Start

# Get an icon SVG
{:ok, svg} = ExIconify.get("lucide:home")

# Get icon (returns fallback on error)
svg = ExIconify.get!("lucide:home")

# Check if icon exists
ExIconify.exists?("lucide:home")

Icon Format

Icons are specified using the format set:icon-name:

lucide:home - Lucide icons
mdi:account - Material Design Icons
tabler:star - Tabler icons
ph:house - Phosphor icons
heroicons:home - Heroicons

Browse all available icons at: https://icon-sets.iconify.design/

Phoenix Integration

For Phoenix/LiveView applications, use the ExIconify.Icon component:

# In your components or live views
import ExIconify.Icon

# In templates
<.icon name="lucide:home" />
<.icon name="mdi:account" class="size-6 text-blue-500" />

Configuration

Configure ExIconify in your config/config.exs:

config :ex_iconify,
  api_url: "https://api.iconify.design",  # Custom API endpoint
  api_timeout: 5_000,                      # Request timeout (ms)
  cache_ttl: :timer.hours(24)              # Cache TTL

How It Works

When you request an icon, ExIconify first checks the ETS cache
If not cached, it fetches the SVG from the Iconify API
The SVG is normalized (colors set to currentColor) and cached
Subsequent requests return the cached version instantly

Icons are cached for 24 hours by default and automatically cleaned up.

Summary

Functions

cache_stats()

Returns cache statistics.

clear_cache()

Clears the icon cache.

exists?(icon_name)

Checks if an icon exists.

fallback_svg()

Returns the fallback SVG used when icon fetch fails.

get(icon_name)

Gets an icon SVG by name.

get!(icon_name)

Gets an icon SVG by name, returning a fallback on error.

parse_icon_name(icon_name)

Parses an icon name into prefix and name components.

preload(icon_names)

Preloads multiple icons into the cache.

Functions

cache_stats()

@spec cache_stats() :: %{size: non_neg_integer(), memory_bytes: non_neg_integer()}

Returns cache statistics.

Examples

iex> stats = ExIconify.cache_stats()
iex> is_integer(stats.size) and is_integer(stats.memory_bytes)
true

clear_cache()

@spec clear_cache() :: :ok

Clears the icon cache.

exists?(icon_name)

@spec exists?(String.t()) :: boolean()

Checks if an icon exists.

Examples

iex> ExIconify.exists?("lucide:home")
true

iex> ExIconify.exists?("lucide:nonexistent")
false

fallback_svg()

@spec fallback_svg() :: String.t()

Returns the fallback SVG used when icon fetch fails.

Examples

iex> svg = ExIconify.fallback_svg()
iex> String.starts_with?(svg, "<svg")
true

get(icon_name)

@spec get(String.t()) :: {:ok, String.t()} | {:error, term()}

Gets an icon SVG by name.

Icons are cached in ETS for fast subsequent access. The icon name should be in the format set:icon-name.

Examples

iex> {:ok, svg} = ExIconify.get("lucide:home")
iex> String.starts_with?(svg, "<svg")
true

iex> ExIconify.get("invalid")
{:error, :invalid_format}

get!(icon_name)

@spec get!(String.t()) :: String.t()

Gets an icon SVG by name, returning a fallback on error.

This is useful in templates where you always want a valid SVG.

Examples

iex> svg = ExIconify.get!("lucide:home")
iex> String.starts_with?(svg, "<svg")
true

iex> svg = ExIconify.get!("invalid:icon")
iex> String.starts_with?(svg, "<svg")
true

parse_icon_name(icon_name)

@spec parse_icon_name(String.t()) :: {:ok, String.t(), String.t()} | :error

Parses an icon name into prefix and name components.

Examples

iex> ExIconify.parse_icon_name("lucide:home")
{:ok, "lucide", "home"}

iex> ExIconify.parse_icon_name("invalid")
:error

preload(icon_names)

@spec preload([String.t()]) :: :ok

Preloads multiple icons into the cache.

Useful for preloading commonly used icons at application startup.

Examples

ExIconify.preload(["lucide:home", "lucide:user", "lucide:settings"])