Add richer icon rendering

Author: dannote

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v0.3.0
+
+- Replace SVG IDs during rendering to avoid duplicate ID collisions
+- Add Iconify-style dimension calculation and `1em` defaults
+- Add `color`, `inline`, and `mask`/`bg` render modes
+
 ## v0.2.0
 
 - Store discovered icons in a readable JSON manifest

README.md

@@ -17,6 +17,7 @@ Most Iconify integrations load icons in JavaScript. PhoenixIconify keeps icons o
 - Icons are discovered from HEEx at compile time
 - Only icons you use are fetched and stored
 - Rendering is plain inline SVG
+- SVG IDs are rewritten to avoid duplicate gradient/mask collisions
 - No browser-side icon loader
 - Works with LiveView diffs and `phx-*` attributes
 - Dynamic icons can be pre-registered in config
@@ -93,6 +94,14 @@ Global attributes are forwarded to the SVG, including `phx-*`, `data-*`, and `ar
 <.icon name="lucide:x" class="size-4" phx-click="close" data-testid="close" />
 ```
 
+Use `color` for currentColor icon sets and `inline` when an icon should align with text:
+
+```heex
+<span>
+  Saved <.icon name="lucide:check" color="green" inline />
+</span>
+```
+
 ## Accessibility
 
 Icons are decorative by default and render with `aria-hidden="true"`:
@@ -116,14 +125,15 @@ Use Tailwind's `size-*` utilities when possible:
 <.icon name="lucide:settings" class="size-5" />
 ```
 
-Or set SVG dimensions directly:
+PhoenixIconify follows Iconify's dimension behavior. Icons default to `1em` high and preserve their aspect ratio. Set one dimension and the other is calculated from the viewBox:
 
 ```heex
 <.icon name="lucide:settings" size="20" />
-<.icon name="lucide:settings" width="1em" height="1em" />
+<.icon name="lucide:settings" height="1em" />
+<.icon name="lucide:settings" width="unset" />
 ```
 
-## Transformations
+## Transformations and render modes
 
 Iconify aliases can include transformations, and you can transform at render time:
 
@@ -134,6 +144,15 @@ Iconify aliases can include transformations, and you can transform at render tim
 <.icon name="lucide:arrow-right" v_flip />
 ```
 
+SVG mode is the default. CSS mask/background modes are available for Iconify-style CSS rendering:
+
+```heex
+<.icon name="lucide:settings" mode="mask" class="size-5" />
+<.icon name="logos:elixir" mode="bg" class="size-5" />
+```
+
+SVG IDs are replaced automatically, so icons with gradients, masks, clip paths, or animation references can be rendered multiple times on the same page.
+
 ## How it works
 
 1. You write `<.icon name="lucide:settings" />`

lib/phoenix_iconify.ex

@@ -26,6 +26,9 @@ defmodule PhoenixIconify do
   attr(:size, :any, default: nil, doc: "Width and height to apply together")
   attr(:width, :any, default: nil, doc: "SVG width attribute")
   attr(:height, :any, default: nil, doc: "SVG height attribute")
+  attr(:color, :string, default: nil, doc: "CSS color for currentColor icons")
+  attr(:inline, :boolean, default: false, doc: "Align icon with text baseline")
+  attr(:mode, :string, default: "svg", doc: "Render mode: svg, mask, or bg")
   attr(:rotate, :integer, default: 0, doc: "Additional 90-degree rotations")
   attr(:flip, :string, default: nil, doc: "Flip direction: horizontal, vertical, or both")
   attr(:h_flip, :boolean, default: false, doc: "Apply horizontal flip")
@@ -35,15 +38,17 @@ defmodule PhoenixIconify do
   def icon(assigns) do
     icon_data = get_icon(assigns.name)
     render_data = render_data(icon_data, assigns)
-    svg_attrs = svg_attrs(assigns, render_data)
 
     assigns =
       assigns
       |> assign(:body, render_data.body)
-      |> assign(:svg_attrs, svg_attrs)
+      |> assign(:svg_attrs, svg_attrs(assigns, render_data))
+      |> assign(:span_attrs, span_attrs(assigns, render_data))
+      |> assign(:svg_mode?, svg_mode?(assigns.mode))
 
     ~H"""
-    <svg {@svg_attrs}><%= if @title do %><title><%= @title %></title><% end %><%= HTML.raw(@body) %></svg>
+    <svg :if={@svg_mode?} {@svg_attrs}><%= if @title do %><title><%= @title %></title><% end %><%= HTML.raw(@body) %></svg>
+    <span :if={!@svg_mode?} {@span_attrs}></span>
     """
   end
 
@@ -105,10 +110,13 @@ defmodule PhoenixIconify do
   defp render_data(%Iconify.Icon{} = icon, assigns) do
     {h_flip, v_flip} = flip_options(assigns.flip, assigns.h_flip, assigns.v_flip)
 
-    {body, viewbox} =
-      Iconify.SVG.build_body(icon, rotate: assigns.rotate, h_flip: h_flip, v_flip: v_flip)
-
-    %{body: body, viewbox: viewbox}
+    Iconify.SVG.build_data(icon,
+      width: assigns.width || assigns.size,
+      height: assigns.height || assigns.size,
+      rotate: assigns.rotate,
+      h_flip: h_flip,
+      v_flip: v_flip
+    )
   end
 
   defp flip_options(flip, h_flip, v_flip) do
@@ -125,16 +133,38 @@ defmodule PhoenixIconify do
       xmlns: "http://www.w3.org/2000/svg",
       viewBox: render_data.viewbox,
       fill: "currentColor",
-      class: assigns.class
+      class: assigns.class,
+      width: render_data.width,
+      height: render_data.height,
+      style: style(assigns.color, assigns.inline)
     }
 
     base
-    |> maybe_put(:width, assigns.width || assigns.size)
-    |> maybe_put(:height, assigns.height || assigns.size)
+    |> Map.merge(accessibility_attrs(assigns))
+    |> Map.merge(assigns.rest)
+    |> Enum.reject(fn {_key, value} -> is_nil(value) or unset_keyword?(value) end)
+    |> Map.new()
+  end
+
+  defp span_attrs(%{mode: "svg"}, _render_data), do: %{}
+
+  defp span_attrs(assigns, render_data) do
+    style =
+      assigns.mode
+      |> String.to_existing_atom()
+      |> span_style(render_data)
+      |> style(assigns.color, assigns.inline)
+
+    %{
+      class: assigns.class,
+      style: style
+    }
     |> Map.merge(accessibility_attrs(assigns))
     |> Map.merge(assigns.rest)
     |> Enum.reject(fn {_key, value} -> is_nil(value) end)
     |> Map.new()
+  rescue
+    ArgumentError -> %{}
   end
 
   defp accessibility_attrs(%{label: label, title: title})
@@ -147,8 +177,77 @@ defmodule PhoenixIconify do
 
   defp accessibility_attrs(_assigns), do: %{"aria-hidden": "true"}
 
-  defp maybe_put(map, _key, nil), do: map
-  defp maybe_put(map, key, value), do: Map.put(map, key, value)
+  defp style(color, inline) do
+    nil
+    |> maybe_style("color", color)
+    |> maybe_style("vertical-align", if(inline, do: "-0.125em"))
+  end
+
+  defp style(style, color, inline) do
+    style
+    |> maybe_style("color", color)
+    |> maybe_style("vertical-align", if(inline, do: "-0.125em"))
+  end
+
+  defp span_style(:mask, render_data) do
+    svg_url = svg_url(render_data)
+
+    [
+      "display:inline-block",
+      "width:#{format_size(render_data.width)}",
+      "height:#{format_size(render_data.height)}",
+      "background-color:currentColor",
+      "mask:var(--svg) no-repeat 50% 50% / 100% 100%",
+      "-webkit-mask:var(--svg) no-repeat 50% 50% / 100% 100%",
+      "--svg:url(\"#{svg_url}\")"
+    ]
+    |> Enum.join(";")
+  end
+
+  defp span_style(:bg, render_data) do
+    svg_url = svg_url(render_data)
+
+    [
+      "display:inline-block",
+      "width:#{format_size(render_data.width)}",
+      "height:#{format_size(render_data.height)}",
+      "background:transparent var(--svg) no-repeat 50% 50% / 100% 100%",
+      "--svg:url(\"#{svg_url}\")"
+    ]
+    |> Enum.join(";")
+  end
+
+  defp maybe_style(style, _key, nil), do: style
+  defp maybe_style(nil, key, value), do: "#{key}:#{value}"
+  defp maybe_style(style, key, value), do: style <> ";#{key}:#{value}"
+
+  defp svg_url(render_data) do
+    [
+      "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"#{render_data.viewbox}\" width=\"#{render_data.width}\" height=\"#{render_data.height}\">",
+      render_data.body,
+      "</svg>"
+    ]
+    |> IO.iodata_to_binary()
+    |> svg_to_url()
+  end
+
+  defp svg_to_url(svg) do
+    svg
+    |> String.replace("%", "%25")
+    |> String.replace("#", "%23")
+    |> String.replace("<", "%3C")
+    |> String.replace(">", "%3E")
+    |> String.replace("\"", "'")
+    |> String.replace("&", "%26")
+  end
+
+  defp format_size(value) when is_number(value), do: to_string(value) <> "px"
+  defp format_size(value), do: value
+
+  defp svg_mode?(mode), do: to_string(mode) == "svg"
+
+  defp unset_keyword?(value) when value in ["unset", "undefined", "none"], do: true
+  defp unset_keyword?(_), do: false
 
   defp handle_missing_icon(normalized, original) do
     maybe_warn(missing_icon_message(normalized, original))

mix.exs

@@ -1,7 +1,7 @@
 defmodule PhoenixIconify.MixProject do
   use Mix.Project
 
-  @version "0.2.0"
+  @version "0.3.0"
   @source_url "https://github.com/elixir-volt/phoenix_iconify"
 
   def project do
@@ -42,7 +42,7 @@ defmodule PhoenixIconify.MixProject do
     if path = System.get_env("ICONIFY_PATH") do
       [path: path]
     else
-      "~> 0.2.0"
+      "~> 0.3.0"
     end
   end
 

test/phoenix_iconify_test.exs

@@ -17,6 +17,13 @@ defmodule PhoenixIconifyTest do
         height: 24
       })
 
+      Manifest.add_icon("lucide:gradient", %Iconify.Icon{
+        name: "lucide:gradient",
+        body: ~s|<defs><linearGradient id="a"></linearGradient></defs><path fill="url(#a)"/>|,
+        width: 32,
+        height: 16
+      })
+
       on_exit(fn -> Manifest.clear_cache() end)
     end
 
@@ -34,6 +41,8 @@ defmodule PhoenixIconifyTest do
       assert html =~ ~s(data-testid="settings")
       assert html =~ ~s(<path d="M10 10"/>)
       assert html =~ ~s(aria-hidden="true")
+      assert html =~ ~s(width="1em")
+      assert html =~ ~s(height="1em")
     end
 
     test "uses accessible label when provided" do
@@ -61,6 +70,34 @@ defmodule PhoenixIconifyTest do
       assert html =~ ~s(width="20")
       assert html =~ ~s(height="20")
     end
+
+    test "supports color, inline alignment, aspect-ratio sizing, and id replacement" do
+      assigns = %{}
+
+      html =
+        rendered_to_string(~H"""
+        <PhoenixIconify.icon name="lucide:gradient" height="1em" color="red" inline />
+        """)
+
+      assert html =~ ~s(width="2em")
+      assert html =~ ~s(height="1em")
+      assert html =~ ~s(style="color:red;vertical-align:-0.125em")
+      assert html =~ ~s(id="iconify-)
+      refute html =~ ~s(id="a")
+    end
+
+    test "supports CSS mask render mode" do
+      assigns = %{}
+
+      html =
+        rendered_to_string(~H"""
+        <PhoenixIconify.icon name="lucide:settings" mode="mask" class="size-5" />
+        """)
+
+      assert html =~ ~s(<span)
+      assert html =~ ~s(class="size-5")
+      assert String.contains?(html, "mask" <> <<58, 118, 97, 114, 40, 45, 45, 115, 118, 103, 41>>)
+    end
   end
 
   describe "normalize_name/1" do