View Source Iconify (iconify_ex v0.6.1)

Phoenix helpers for using 100,000+ SVG icons from 100+ icon sets compiled by Iconify (visit that site to browse the sets available and preview the icons)

It copies only the icons you use from the iconify library into your project, preparing them on-the-fly when you first use an icon in a view or component (either at compile time if using the Surface component, or on the first run during development).

It can be configured to embed the icons one of three ways:

  • css (default): generate a single CSS file containing SVGs of all the icons used
  • img (default for emojis): to create SVG files in your static assets, used to be included with img tags and loaded over HTTP (you may want to include svg-inject on your site to enable styling of the SVGs, e.g. to change their colour)
  • inline: to generate a Phoenix Component for each icon used, used to embed the icons as svg tags inline in the HTML of your views (meaning the SVG will be included in LiveView diffs)
  • set: to generate an SVG sprite set for each family, and reference icons with a use tag inside of inline SVGs.

There is also an optional integration of phoenix_live_favicon so you can set an icon (or emoji) as favicon on a page with Iconify.maybe_set_favicon(socket, icon_name_or_emoji).

Installation

def deps do
  [
    {:iconify_ex, "~> 0.1.0"}
  ]
end

After running mix deps.get you need to fetch the latest iconify icon sets by running something like:

cd deps/iconify_ex/assets && yarn && cd -

Usage

  1. Add import Iconify in your Phoenix or LiveView module where you want to use it (or just once in the macros in your Web module).

  2. Set one of these options in config to choose which approach you want to use (see above for explanations):

  • config :iconify_ex, :mode, :css
  • config :iconify_ex, :mode, :img
  • config :iconify_ex, :mode, :inline
  • config :iconify_ex, :mode, :set

Along with this config :iconify_ex, :env, config_env() so the library knows when to prepare icons (only when not in prod env).

If using CSS mode, you'll need to include the CSS file in your layout (e.g. <link phx-track-static rel="stylesheet" href={~p"/images/icons/icons.css"} /> in your app's equivalent of lib/my_app_web/components/layouts/root.html.heex) and set some default styles that will be applied to all icons, by adding something like this to your app's main CSS (e.g. assets/css/app.css):

[iconify] {
  background-color: currentColor;
  -webkit-mask-size: cover;
  mask-size: cover;
  min-width: 0.5rem;
  min-height: 0.5rem;
}

Other configurations include:

config :iconify_ex, :fallback_icon, "heroicons-solid:question-mark-circle" # when an icon is not found
config :iconify_ex, :generated_icon_modules_path, "./lib/web/icons" # for :inline mode
config :iconify_ex, :generated_icon_static_path, "./priv/static/images/icons" # where CSS and images are stored
config :iconify_ex, :generated_icon_static_url, "/images/icons/" # where CSS and images are served from
  1. In all three cases, usage is the same (meaning you can easily switch between modes at any time) by including a component:

Embed an icon using default classes (copy the icon name from the iconify website):

<.iconify icon="heroicons-solid:collection" />

Specify custom classes:

<.iconify icon="heroicons-solid:collection" class="w-8 h-8 text-base-content" /> 

Or if you use Surface, it is highly recommended to use the macro component which means icons will be prepared at compile time rather than runtime:

Add alias Iconify.Icon to your Web module, and then:

<#Icon iconify="heroicons-solid:collection" />

If your icon is dynamic, you'll still want to use the first form:

<.iconify icon={@my_icon} />

Note: when using the CSS mode, there's sometimes a race condition that adds an icon several times. Until a fix is found you can run something like sort -u -o icons_dir/icons.css icons_dir/icons.css to clean up the CSS file.

Summary

Functions

Checks if the icon is part of a known emoji set or any set shouldn't use CSS mode (eg. includes color or animation).

Checks if the icon is part of a known emoji set

Returns the fallback icon name.

Generates CSS icons from existing components.

Generates CSS icons from existing static files.

Generates icon sets from existing components.

Renders an icon as a Phoenix.Component based on the given assigns.

Lists all existing icons (components and CSS).

Lists all available icon components.

Lists all icons defined in the CSS file.

Prepares and renders an icon.

Sets the favicon for a Phoenix LiveView socket.

Returns the configured path for generated icon modules.

Prepares an icon based on the given assigns and mode (such as CSS, inline SVG, or image URL).

Prepares an entire icon family for a particular mode.

Returns the configured path for generated static icon assets.

Returns the configured URL for generated static icon assets.

Checks if SVG injection is enabled in config.

Functions

add_icon_to_css(icon_css_name, svg_code)

complex?(icon)

Checks if the icon is part of a known emoji set or any set shouldn't use CSS mode (eg. includes color or animation).

Examples

iex> Iconify.complex?("twemoji:smile")
true
iex> Iconify.complex?("heroicons-solid:user")
false

emoji?(icon)

Checks if the icon is part of a known emoji set

Examples

iex> Iconify.emoji?("twemoji:smile")
true
iex> Iconify.emoji?("heroicons-solid:user")
false

fallback_icon()

Returns the fallback icon name.

Examples

iex> Iconify.fallback_icon()
"heroicons-solid:question-mark-circle"

generate_css_from_components()

Generates CSS icons from existing components.

Examples

iex> Iconify.generate_css_from_components()
:ok

generate_css_from_static_files()

Generates CSS icons from existing static files.

Examples

iex> Iconify.generate_css_from_static_files()
:ok

generate_sets_from_components()

Generates icon sets from existing components.

Examples

> Iconify.generate_sets_from_components()
[:ok, :ok, _]

iconify(assigns)

Renders an icon as a Phoenix.Component based on the given assigns.

Examples

iex> assigns = %{icon: "heroicons-solid:user", class: "w-6 h-6", __changed__: nil}
iex> Iconify.iconify(assigns) # Returns rendered icon HTML

list_all_existing()

Lists all existing icons (components and CSS).

Examples

> Iconify.list_all_existing()
%{
  "HeroiconsSolid" => [Iconify.HeroiconsSolid.User, "user", _],
  "HeroiconsOutline" => [Iconify.HeroiconsOutline.User, "user", _]
}

list_components()

Lists all available icon components.

Examples

> Iconify.list_components()
%{
  "HeroiconsSolid" => [Iconify.HeroiconsSolid.User, Iconify.HeroiconsSolid.Star, _],
  "HeroiconsOutline" => [Iconify.HeroiconsOutline.User, Iconify.HeroiconsOutline.Star, _]
}

list_icons_in_css()

Lists all icons defined in the CSS file.

Examples

> Iconify.list_icons_in_css()
%{
  "HeroiconsSolid" => ["user", "star", _],
  "HeroiconsOutline" => ["user", "star", _]
}

list_icons_in_images()

manual(icon, opts \\ nil)

Prepares and renders an icon.

Examples

iex> %Phoenix.LiveView.Rendered{} = Iconify.manual("heroicons-solid:user", mode: :css) # Returns rendered icon HTML or data

maybe_phx_live_set_dynamic(socket, icon, type \\ "svg")

maybe_set_favicon(socket, icon)

Sets the favicon for a Phoenix LiveView socket.

Examples

iex> socket = %Phoenix.LiveView.Socket{}
iex> %Phoenix.LiveView.Socket{} = Iconify.maybe_set_favicon(socket, "heroicons-solid:star")

path()

Returns the configured path for generated icon modules.

Examples

iex> Iconify.path()
"./lib/web/icons"

preparation_enabled?()

prepare(assigns, opts \\ [])

Prepares an icon based on the given assigns and mode (such as CSS, inline SVG, or image URL).

Examples

iex> {:css, _function, %{icon: "heroicons-solid:user", class: "w-4 h-4", icon_name: "heroicons-solid:user"}} = Iconify.prepare(%{icon: "heroicons-solid:user", __changed__: nil}, :css)

iex> {:inline, _fun, %{icon: "heroicons-solid:user"}} = Iconify.prepare(%{icon: "heroicons-solid:user", __changed__: nil}, :inline)

iex> {:img, _fun, %{src: "/images/icons/heroicons-solid/user.svg"}} = Iconify.prepare(%{icon: "heroicons-solid:user", __changed__: nil}, :img)

iex> {:set, _fun, %{href: "/images/icons/heroicons-solid.svg#user"}} = Iconify.prepare(%{icon: "heroicons-solid:user", __changed__: nil}, :set)

iex> {:img, _fun, %{src: "/images/icons/twemoji/rabbit.svg"}} = Iconify.prepare(%{icon: "twemoji:rabbit", __changed__: nil})

iex> {:css, _fun, %{icon_name: "heroicons-solid:question-mark-circle"}} = Iconify.prepare(%{icon: "non-existent-icon", __changed__: nil})

 > Iconify.prepare(%{icon: "<svg>...</svg>", __changed__: nil})
{:inline, _fun, %{icon: "<svg>...</svg>"}}

prepare_entire_icon_family(family_name, mode \\ nil)

Prepares an entire icon family for a particular mode.

Examples

iex> Iconify.prepare_entire_icon_family("heroicons-solid", :inline) # creates a Phoenix.Component module file for each icon in the set

static_path()

Returns the configured path for generated static icon assets.

Examples

iex> Iconify.static_path()
"./priv/static/images/icons"

static_url()

Returns the configured URL for generated static icon assets.

Examples

iex> Iconify.static_url()
"/images/icons"

using_svg_inject?()

Checks if SVG injection is enabled in config.

Examples

iex> Iconify.using_svg_inject?()
false