> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluid.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> For new direct REST integrations, use the v2026-04 surfaces. The @fluid-app FairShare SDK continues to use its own published public-v2025-06 contract.
> Authenticate with the header Authorization: Bearer <token>; public storefront read endpoints require no auth.
> Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null.
> Never use /api/company/v1 or /api/v1 paths, page/per_page params, or offset pagination — they are legacy.
> The OpenAPI specs under api-reference/ are the authoritative contracts; prefer them over prose when in doubt. api-reference/storefront-v2026-04.yaml covers the v2026-04 storefront surface (/api/v202604/... paths); api-reference/auth-v0.yaml covers the unversioned auth surface (/api/... paths — authentication, MFA, social auth, and token exchange); api-reference/checkout-v2026-04.yaml covers the v2026-04 checkout surface (/api/checkout/v2026-04/... paths — carts, cart auth, discounts, items, subscriptions, orders, enrollments, and store config); api-reference/public-v2025-06.yaml covers the Public SDK surface used by the @fluid-app FairShare SDK, including its parallel cart lifecycle, browser integrations, versioned payment callbacks, unversioned public utilities, and the cart price-override operation; api-reference/payment-v2026-04.yaml covers the v2026-04 payment gateway admin surface (/api/payment/v2026-04/... paths, bearer-authenticated — gateway CRUD, gateway purchase/authorize/$0-verify, transaction list/show and capture/void/credit, and merchant payment configuration); api-reference/payments-v2026-04.yaml covers the v2026-04 cart payment surface (/api/payments/v2026-04/carts/{cart_token}/... paths, authenticated by the cart token in the path with no bearer — payment-method selection, VGS card tokenization, 3D Secure verification, and PayPal/Braintree/Klarna/Apple Pay flows); api-reference/commerce-v2026-04.yaml covers the v2026-04 commerce order-editing surface (/api/v202604/orders/{order_id}/edits paths, bearer-authenticated — post-checkout order edits that atomically insert items and add adjustments/discounts, with an optional dry-run preview); api-reference/webhooks-v0.yaml covers the unversioned webhooks surface (/api/... paths — webhook registration, delivery payloads, callback registrations, company events, and webhook/callback schemas).
> Successful responses wrap the resource payload alongside a top-level integer status and a meta object.

# Render responsive media

> Render responsive images and videos with the media_tag Liquid filter.

Use the `media_tag` filter to turn an image or video value into complete HTML
markup:

```liquid theme={null}
{{ section.settings.hero_image | media_tag }}
```

The filter accepts a URL string, a media value, or a hash with a `url` or `src`
key. It returns an empty string for an empty input.

Fluid renders a `<video>` when the media type is `video` or when the URL path
ends in `.mp4`, `.mov`, `.webm`, or `.m4v`. Other inputs render as `<img>`.

## Render responsive images

For an image on Fluid's ImageKit host, the default output includes:

* A `srcset` with widths `400`, `800`, `1200`, and `1600`
* `sizes="100vw"`
* ImageKit quality `80` and format `auto`
* `loading="lazy"` and `decoding="async"`
* An empty `alt` value unless the input supplies alt text

```liquid theme={null}
{{ section.settings.hero_image
  | media_tag:
    sizes: "(max-width: 768px) 100vw, 720px",
    alt: "Trail running shoes on sandstone",
    class: "hero__image"
}}
```

Use these options to control the result:

| Option      | Default                | Effect                                                                                        |
| ----------- | ---------------------- | --------------------------------------------------------------------------------------------- |
| `sizes`     | `100vw`                | Describes the image's rendered width to the browser.                                          |
| `widths`    | `400,800,1200,1600`    | Sets the comma-separated `srcset` width ladder.                                               |
| `width`     | —                      | Uses the requested width and its 2× width, adds `width`, and defaults `sizes` to `{width}px`. |
| `height`    | —                      | Adds the HTML `height` attribute.                                                             |
| `quality`   | `80`                   | Sets ImageKit image quality.                                                                  |
| `format`    | `auto`                 | Sets the ImageKit output format.                                                              |
| `crop`      | —                      | Sets the ImageKit focus to `top`, `bottom`, `left`, `right`, or `center`.                     |
| `transform` | —                      | Adds raw ImageKit transformation tokens to each rendition.                                    |
| `loading`   | `lazy`                 | Sets the HTML loading behavior.                                                               |
| `alt`       | Input alt text or `""` | Sets the image alternative text.                                                              |

When the input includes intrinsic dimensions, Fluid adds `width` and `height`
attributes. It also caps the responsive width ladder at the intrinsic width.

For a fixed-size image, pass `width`:

```liquid theme={null}
{{ section.settings.logo | media_tag: width: 240, alt: "Juniper Supply" }}
```

This creates `240w` and `480w` renditions and sets `sizes="240px"`.

<Note>
  Do not add a `w-` token to `transform`. Use `width` or `widths` so the
  transformation stays aligned with `srcset`.
</Note>

## Render videos

ImageKit-hosted videos request MP4 output by default. Fluid also generates a
poster URL from the first frame unless you supply `poster`.

```liquid theme={null}
{{ section.settings.background_video
  | media_tag:
    autoplay: true,
    loop: true,
    muted: true,
    class: "hero__video"
}}
```

The result includes `autoplay`, `loop`, `muted`, and `playsinline`.
`playsinline` is added automatically when you enable `muted` or `autoplay`.

| Option             | Default                        | Effect                                         |
| ------------------ | ------------------------------ | ---------------------------------------------- |
| `autoplay`         | Off                            | Adds the `autoplay` attribute.                 |
| `loop`             | Off                            | Adds the `loop` attribute.                     |
| `muted`            | Off                            | Adds the `muted` attribute.                    |
| `controls`         | Off                            | Adds native video controls.                    |
| `poster`           | ImageKit first-frame thumbnail | Overrides the generated poster URL.            |
| `format`           | `mp4`                          | Sets the ImageKit video format.                |
| `quality`          | —                              | Sets ImageKit video quality.                   |
| `width` / `height` | —                              | Sets ImageKit video dimensions.                |
| `transform`        | —                              | Adds raw ImageKit video transformation tokens. |

## Handle external media and attributes

For media outside Fluid's configured ImageKit host, the filter preserves the
original URL. External images do not receive a transformed `srcset`. External
videos do not receive an ImageKit format transformation or generated poster.

Options such as `class`, `id`, `style`, `data-*`, and `fetchpriority` pass
through as HTML attributes. Fluid escapes attribute values and removes every
attribute whose name starts with `on`, such as `onerror` or `onload`.

For direct URL transformations, see
[image transformations](/themes/image-transformations). For available theme
data, see [theme variables](/themes/theme-variables).