Image.Components (image_components v0.1.0)

Copy Markdown View Source

Phoenix.Component wrappers for the image / image_plug ecosystem.

Exposes two LiveView-friendly components — <.image> and <.picture> — that take per-transform attributes (width, height, fit, format, blur, brightness, …), build a canonical Image.Plug.Pipeline, and project that pipeline onto the URL grammar of one of five supported providers via Image.Components.URL: four commercial image CDNs (Cloudflare Images, Cloudinary, imgix, ImageKit) plus IIIF Image API 3.0.

Use this module like any other Phoenix.Component:

defmodule MyAppWeb.PageLive do
  use MyAppWeb, :live_view
  import Image.Components

  def render(assigns) do
    ~H"""
    <.image src="/uploads/cat.jpg" provider={:cloudflare} width={600} fit={:cover} />
    """
  end
end

Each component renders a plain HTML element (<img> or <picture>); the only "magic" is constructing the URL. There is no JavaScript and no LiveView-specific behavior.

Provider feature gaps

Not every transform is expressible in every CDN's URL grammar. Operations that don't have a faithful equivalent are silently dropped from the URL projection — see Image.Components.URL for the per-provider coverage table.

Summary

Functions

image(assigns)

Renders an <img> whose src is built by projecting the attribute set onto the configured CDN provider's URL grammar.

picture(assigns)

Renders a <picture> element with format-specific <source srcset> rows that share the rest of the transform set, plus a fallback <img>.

Functions

image(assigns)

Renders an <img> whose src is built by projecting the attribute set onto the configured CDN provider's URL grammar.

Attributes

  • src — the canonical, untransformed source path or URL (e.g. /uploads/cat.jpg). Required.

  • provider — :cloudflare, :cloudinary, :imgix, or :imagekit. Required.

  • host — optional URL prefix (e.g. "https://cdn.example.com" or "/img"). Defaults to "" (relative URL).

  • width, height — pixel dimensions. Optional.

  • fit — one of :contain, :cover, :crop, :pad, :scale_down, :squeeze. Optional.

  • gravity — :center, :auto, :face, :north, :south, :east, :west, :north_east, :north_west, :south_east, :south_west, or {:xy, x, y}. Optional.

  • dpr — device-pixel-ratio multiplier. Optional.

  • face_zoom — float in [0.0, 1.0] controlling how tightly a face-aware crop hugs the detected face. 0.0 is a loose crop with lots of context, 1.0 hugs the bounding box. Only meaningful with gravity={:face}. Optional.

  • format — :auto, :jpeg, :png, :webp, :avif. Optional.

  • quality — 1..100. Optional.

  • blur, sharpen — sigma (float ≥ 0). Optional.

  • brightness, contrast, saturation, gamma — multipliers where 1.0 means no change. Optional.

  • vignette — strength in [0.0, 1.0]. Only Cloudinary's URL grammar carries vignette; other providers drop it. Optional.

  • tint — colour as a hex string ("#aabbcc" or "aabbcc") or an [r, g, b] integer list. Only imgix's monochrome= carries this; other providers drop it. Optional.

  • cloudinary_account — the Cloudinary <cloud-name> segment. Defaults to "demo".

  • imagekit_endpoint — the ImageKit per-account endpoint segment. Defaults to "demo".

  • class, alt, plus any other arbitrary HTML attributes — passed through to the rendered <img> via :rest.

Returns

  • Renders a single <img> element.

Examples

<.image src="/cat.jpg" provider={:cloudflare} width={600} fit={:cover} />

<.image
  src="/cat.jpg"
  provider={:imgix}
  host="https://my-source.imgix.net"
  width={800}
  format={:webp}
  quality={80}
  blur={5.0}
/>

Attributes

  • src (:string) (required)
  • provider (:atom) (required) - Must be one of :cloudflare, :cloudinary, :imgix, :imagekit, or :iiif.
  • host (:string) - Defaults to "".
  • width (:integer) - Defaults to nil.
  • height (:integer) - Defaults to nil.
  • fit (:atom) - Defaults to nil.
  • gravity (:any) - Defaults to nil.
  • dpr (:integer) - Defaults to nil.
  • face_zoom (:float) - Defaults to nil.
  • format (:atom) - Defaults to nil.
  • quality (:integer) - Defaults to nil.
  • blur (:float) - Defaults to nil.
  • sharpen (:float) - Defaults to nil.
  • brightness (:float) - Defaults to nil.
  • contrast (:float) - Defaults to nil.
  • saturation (:float) - Defaults to nil.
  • gamma (:float) - Defaults to nil.
  • vignette (:float) - Defaults to nil.
  • tint (:any) - Defaults to nil.
  • region (:any) - Defaults to nil.
  • iiif_quality (:atom) - Defaults to nil.Must be one of :default, :color, :gray, :bitonal, or nil.
  • cloudinary_account (:string) - Defaults to "demo".
  • imagekit_endpoint (:string) - Defaults to "demo".
  • iiif_prefix (:string) - Defaults to "/iiif/3".
  • iiif_format (:atom) - Defaults to :jpeg.
  • Global attributes are accepted. Supports all globals plus: ["alt", "class", "srcset", "sizes", "loading", "decoding", "fetchpriority"].

picture(assigns)

Renders a <picture> element with format-specific <source srcset> rows that share the rest of the transform set, plus a fallback <img>.

Attributes

Same as image/1, with one extra:

  • formats — list of formats to emit as <source> rows. Defaults to [:avif, :webp]. The fallback <img> uses format if given, otherwise the original format.

Returns

  • Renders a <picture> element with one <source> per requested format and a single <img> fallback.

Examples

<.picture src="/cat.jpg" provider={:cloudflare} width={600} formats={[:avif, :webp]} />

Attributes

  • src (:string) (required)
  • provider (:atom) (required) - Must be one of :cloudflare, :cloudinary, :imgix, :imagekit, or :iiif.
  • host (:string) - Defaults to "".
  • formats (:list) - Defaults to [:avif, :webp].
  • width (:integer) - Defaults to nil.
  • height (:integer) - Defaults to nil.
  • fit (:atom) - Defaults to nil.
  • gravity (:any) - Defaults to nil.
  • dpr (:integer) - Defaults to nil.
  • face_zoom (:float) - Defaults to nil.
  • format (:atom) - Defaults to nil.
  • quality (:integer) - Defaults to nil.
  • blur (:float) - Defaults to nil.
  • sharpen (:float) - Defaults to nil.
  • brightness (:float) - Defaults to nil.
  • contrast (:float) - Defaults to nil.
  • saturation (:float) - Defaults to nil.
  • gamma (:float) - Defaults to nil.
  • vignette (:float) - Defaults to nil.
  • tint (:any) - Defaults to nil.
  • region (:any) - Defaults to nil.
  • iiif_quality (:atom) - Defaults to nil.Must be one of :default, :color, :gray, :bitonal, or nil.
  • cloudinary_account (:string) - Defaults to "demo".
  • imagekit_endpoint (:string) - Defaults to "demo".
  • iiif_prefix (:string) - Defaults to "/iiif/3".
  • iiif_format (:atom) - Defaults to :jpeg.
  • Global attributes are accepted. Supports all globals plus: ["alt", "class", "loading", "decoding", "fetchpriority"].