# `Image.Components`
[🔗](https://github.com/elixir-image/image_components/blob/v0.1.1/lib/image/components.ex#L1)

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](https://iiif.io/api/image/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.

# `image`

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`

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"]`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*