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

IIIF Image API 3.0-specific Phoenix components.

`<.image provider={:iiif}>` covers the static-thumbnail case —
it emits a single `<img>` whose `src` is built by
`Image.Components.URL.iiif/2`. This module covers the IIIF
fundamentals that don't fit the cross-provider component shape:

  * **`:static` mode** — same as `<.image provider={:iiif}>`,
    but lives here for symmetry with the other modes. Renders a
    single `<img>`.

  * **`:tiles` mode** — emits a CSS grid of `<img>` tiles at a
    chosen scale factor. No JavaScript. Useful for high-resolution
    static layouts (atlases, scanned documents) where the tile
    structure of the IIIF source maps cleanly onto a fixed-size
    grid.

  * **`:viewer` mode** — emits a `<div>` carrying
    `data-iiif-info-url=…`, ready for a JavaScript deep-zoom
    viewer (OpenSeadragon, Mirador, Leaflet-IIIF) to mount into.
    A static fallback `<img>` lives inside the div for the
    no-JS / loading-state case.

Use this module when your image source is IIIF-compliant *and*
you need tiling or viewer mounting. For thumbnails, use the
generic `<.image provider={:iiif}>` from `Image.Components`.

## Usage

    defmodule MyAppWeb.GalleryLive do
      use MyAppWeb, :live_view
      import Image.Components.IIIF

      def render(assigns) do
        ~H"""
        <%!-- Static thumbnail --%>
        <.iiif src="/cat.jpg" host="https://iiif.example.org" width={400} />

        <%!-- Tile grid for a 4096×4096 source at scale factor 2 --%>
        <.iiif
          src="/atlas.jpg"
          host="https://iiif.example.org"
          mode={:tiles}
          source_width={4096}
          source_height={4096}
          tile_width={512}
          scale_factor={2}
        />

        <%!-- Deep-zoom viewer mount --%>
        <.iiif
          src="/portrait.jpg"
          host="https://iiif.example.org"
          mode={:viewer}
          width={800}
          height={600}
          phx-hook="OpenSeadragon"
          id="viewer-1"
        />
        """
      end
    end

See [the IIIF guide](https://hexdocs.pm/image_components/iiif.html)
for the per-mode walkthrough and the JavaScript-viewer wiring
recipe.

# `iiif`

Renders an IIIF image. See the moduledoc for mode descriptions.

### Attributes

Common to all modes:

* `src` — the IIIF identifier path. Required.

* `host` — the IIIF server's host (e.g. `"https://iiif.example.org"`).
  Defaults to `""`.

* `iiif_prefix` — the server's IIIF version prefix segment.
  Defaults to `"/iiif/3"`.

* `mode` — `:static` (default), `:tiles`, or `:viewer`.

Static mode uses every per-transform attribute that
`Image.Components.image/1` accepts (`width`, `height`, `fit`,
`region`, `iiif_quality`, `format`, …) — see that component's docs.

Tile mode (`mode={:tiles}`):

* `source_width`, `source_height` — the source image's pixel
  dimensions, *required*. (Discover them from `info.json` if you
  don't have them — the discovery step is out of scope here.)

* `tile_width` — pixel width of each rendered tile. Defaults to
  `512` (the IIIF Image API 3.0 default tile size). Pass the
  server's actual `tiles[0].width` from `info.json` for tightest
  cache alignment with the server's pre-computed tiles.

* `tile_height` — defaults to `tile_width` (square tiles).

* `scale_factor` — integer; the tiles cover `tile_width *
  scale_factor` source pixels each, rendered at `tile_width`.
  `1` is full resolution. Higher = more pixels per tile, fewer
  tiles total. Defaults to `1`.

* `format`, `iiif_quality` — applied to every tile URL. Default
  `:jpeg` and `:default`.

Viewer mode (`mode={:viewer}`):

* `width`, `height` — pixel size of the viewer container. CSS
  pixels. Defaults to `800` × `600`.

* `viewer` — informational atom passed through as
  `data-iiif-viewer="…"` so a JS hook can dispatch on viewer
  family. Defaults to `:openseadragon`. Other common values:
  `:mirador`, `:leaflet`.

* `fallback_size` — width passed to the static fallback `<img>`
  inside the viewer div. Shown before JS mounts. Defaults to
  `800`.

* Any `phx-hook=…`, `id=…`, `class=…`, or other HTML attributes
  pass through to the outer `<div>` via `:rest`.

### Returns

* Renders an `<img>` (static), a wrapper `<div>` containing
  a CSS grid of `<img>` tiles (tiles), or a wrapper `<div>`
  with viewer-mount data attributes plus a fallback `<img>`
  (viewer).

## Attributes

* `src` (`:string`) (required)
* `host` (`:string`) - Defaults to `""`.
* `iiif_prefix` (`:string`) - Defaults to `"/iiif/3"`.
* `mode` (`:atom`) - Defaults to `:static`. Must be one of `:static`, `:tiles`, or `:viewer`.
* `width` (`:integer`) - Defaults to `nil`.
* `height` (`:integer`) - Defaults to `nil`.
* `fit` (`:atom`) - Defaults to `nil`.
* `region` (`:any`) - Defaults to `nil`.
* `iiif_quality` (`:atom`) - Defaults to `nil`.Must be one of `:default`, `:color`, `:gray`, `:bitonal`, or `nil`.
* `format` (`:atom`) - Defaults to `nil`.
* `iiif_format` (`:atom`) - Defaults to `:jpeg`.
* `source_width` (`:integer`) - Defaults to `nil`.
* `source_height` (`:integer`) - Defaults to `nil`.
* `tile_width` (`:integer`) - Defaults to `512`.
* `tile_height` (`:integer`) - Defaults to `nil`.
* `scale_factor` (`:integer`) - Defaults to `1`.
* `viewer` (`:atom`) - Defaults to `:openseadragon`.
* `fallback_size` (`:integer`) - Defaults to `800`.
* Global attributes are accepted. Supports all globals plus: `["alt", "class", "id", "loading", "decoding", "fetchpriority", "phx-hook", "phx-update", "style"]`.

---

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