SvgIcons creates helpers to inject inline svgs into your Phoenix, Phoenix LiveView, and Surface templates without having to manually manage the svgs.

It was originally created to help with the heroicon set that is released and maintained by the tailwind developers (and for use with tailwind ui); however, I've found it's useful for other cases as well.

Usage

To use SvgIcons, create a module and simple use SvgIcons. The following options are supported:

• :path - (required) the path expression to find svg files
• :path_sep - the path separator to use (defaults to /)
• :ext - the file extension (defaults to .svg)
• :base_dir - the base directory to resolve path from (defaults to the directory the module is located in)
• :surface - should a surface MacroComponent be generated in addition to the svg utility function? (defaults to true)

Path expression

This is how you specify the location and identification properties for the svgs in an icon set. A path expression is a list composed of literal strings, atoms, and tuples. Literal strings are interpreted as literal path segments, an atom the name of a single path segment, and tuples allow you to specify the name, allowed values, and the default value for a path segment.

For example:

• "dist/optimized" is a treated as a static path segment
• :variant is treated as a variable path segment named variant
• {:variant, "outline"} is treated as a variable path segment named variant and default value "outline"
• {:variant, [:outline, :solid]} is treated as a variable path segment named variant that allows the values outline and solid
• {:vairant, [:outline, :solid], "outline"} is treated as a variable path segment named variant that allows either outline or solid and defaults to outline

Putting that together, ["dist/optimized", {:group, "all"}, {:variant, [:outline, :solid]}, :icon] specifies the following path: dist/optimized/#{group || "all"}/#{variant}/#{icon}.svg, with variant limited to either outline or solid. The module enumerates all potential paths for files that match, reads them in, and tells elixir that they are external resources (ensuring the module will be recompiled if any of them change). Each file should be a single svg element.

There are two ways to use the module. If you have surface in your dependencies, it will turn the module into a MacroComponent where each of the variables from the path expression are exposed as props along with class and opts where class is treated as the class attribute, and opts are treated as a keyword list of attribute name, attribute value pairs that are injected into the svg.

Examples

Hero Icons

$ git submodule init https://github.com/tailwindlabs/heroicons svgs/heroicons

defmodule HeroIcon do
  use SvgIcons,
    path: ["svgs/heroicons/optimized", {:variant, [:outline, :solid], "outline"}, :icon]
end

defmodule Component do
  use Surface.Component

  def render(assigns) do
    ~F"""
    <#HeroIcon variant="solid" icon="dots-vertical" class="w-5 h-5" />
    """
  end
end

defmodule PhoenixComponent do
  use Phoenix.LiveComponent

  def render(assigns) do
    ~L"""
    <%= HeroIcon.svg({"solid", "dots-vertical"}, class: "w-5 h-5")
    """
  end
end

Remix Icons

$ git submodule init https://github.com/Remix-Design/RemixIcon svgs/remixicon

defmodule RemixIcon do
  use SvgIcons,
    path: ["svgs/remixicon", :group, :icon]
end

defmodule Component do
  use Surface.Component

  def render(assigns) do
    ~F"""
    <#RemixIcon group="Editor" icon="bold" class="w-5 h-5 text-current" />
    """
  end
end

defmodule PhoenixComponent do
  use Phoenix.LiveComponent

  def render(assigns) do
    ~L"""
    <%= RemixIcon.svg({"Editor", "bold"}, class: "w-5 h-5 text-current")
    """
  end
end