> ## Documentation Index
> Fetch the complete documentation index at: https://autorender.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Attributes
> Every data-ar-* attribute Autorender Native reads — sources, backgrounds, transforms, intrinsic size, eager loading, and view containers.
Autorender Native is driven entirely by `data-ar-*` attributes on your HTML. You mark an element, the runtime measures it, builds a delivery URL, and loads the result. This page lists every attribute and what it does.
The **Put it on** column is the element the attribute belongs on: an ``, any element used as a background, or the container that wraps a group.
| Attribute | Put it on | Meaning |
| -------------------- | ------------------- | ------------------------------------------------------------ |
| `data-ar-src` | `` | Source path in your workspace, or an `https://` URL to fetch |
| `data-ar-background` | any element | Background image source |
| `data-ar-transform` | image or background | `*` (CSS-derived, the default) plus optional raw tokens |
| `data-ar-intrinsic` | image or background | `"1600x1200"` — source dimensions; caps upscaling |
| `data-ar-step` | image or background | Per-element width-step override |
| `data-ar-eager` | image or background | Skip visibility-based lazy loading |
| `data-ar-view` | container | Load all contained media together |
| `data-ar-measure` | image or background | `compat` forces the compatibility measurement path |
### Value syntax and invalid values
Every attribute has a defined fallback when its value is malformed, so a typo never disables the element. With [`debug=1`](/docs/native/configuration) the runtime logs each rejection.
| Attribute | Value | If invalid or missing |
| -------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------- |
| `data-ar-src` | Source path, or an `https://` URL | A non-`http(s)` scheme is rejected and the element is skipped |
| `data-ar-background` | Source path, or an `https://` URL | Same as `data-ar-src` |
| `data-ar-transform` | `*` plus optional raw tokens, comma-separated | Each malformed or unsafe token is dropped; the rest still apply |
| `data-ar-intrinsic` | `WIDTHxHEIGHT`, e.g. `1600x1200` | Ignored — no upscale cap is applied |
| `data-ar-step` | Integer **1**–**512** | Falls back to the global [`step`](/docs/native/configuration), not the built-in default |
| `data-ar-eager` | Present (boolean) | — |
| `data-ar-view` | Present (boolean), on a container | — |
| `data-ar-measure` | `compat` | Ignored — normal measurement is used |
## How do I load an image?
Add `data-ar-src` to an `` with the source path inside your workspace. Give it a `width` and `height` so the browser reserves space before the image loads.
```html theme={null}
```
To optimize a remote image, pass a full `https://` URL. The runtime routes it through Autorender's remote fetch:
```html theme={null}
```
Remote fetch works for any publicly reachable `https://` URL. The client validates the scheme only; Autorender fetches the origin server-side, caps the response at **100 MB**, times out after **30 seconds**, and rejects HTML and XML responses. A URL behind authentication does not load, because the fetch carries no credentials. Point it at a stable, public URL.
The runtime sets only the element's `src`. An existing `srcset` still wins in the browser, so the optimized `src` is ignored — remove `srcset` from any marked ``, and mark a plain `` rather than a ``. A native `loading="lazy"` attribute is harmless; the runtime runs its own lazy loading regardless.
## How do I load a background image?
Add `data-ar-background` to any element. The runtime sets the element's `background-image` to an optimized URL sized to the element's box.
```html wrap theme={null}
```
An existing gradient layer is kept; the Autorender image is composed beneath it.
Give the element a height (or an `aspect-ratio`). A background box with no height measures zero, so the runtime cannot size it and falls back to the compatibility path.
## How does `data-ar-transform` work?
`data-ar-transform` defaults to `*`, which derives the sizing tokens from the element's live CSS. You do not need to set it for standard responsive behavior.
The `*` mapping:
| Element CSS | Generated tokens |
| -------------------------------------------------------------------------- | -------------------------------------------------- |
| `` with `object-fit: cover` | `c_fill` + width + height |
| `` with `object-fit: contain` | `c_fit` + width + height |
| ``, any other `object-fit` | width only; height follows the source aspect ratio |
| background with `background-size: cover` \| `contain` | maps the same as the `` cases above |
| background with any other `background-size` (including the default `auto`) | width only; no crop token |
You can combine raw Autorender tokens with `*`:
```html theme={null}
```
Any Autorender transform prefix of **1–6 lowercase letters** is accepted, followed by a value of **up to 64 characters** from a safe character class (`[A-Za-z0-9._:+-]`). A token that fails either check — malformed or injection-unsafe — is dropped, never inserted into a URL, and `debug` mode logs the rejection.
### `W` and `H` size aliases
Inside a token value, the uppercase aliases `W` and `H` are replaced at build time with the element's live, bucketed rendered width and height. Simple arithmetic on the aliases is supported and evaluated by a safe parser — never `eval` or `new Function`.
```html theme={null}
```
An alias value may contain only the aliases, digits, `.`, the `x` / `X` / `:` separators, parentheses, and the `+ - * /` operators, up to **64 characters**. Any other character — or a malformed expression, or a literal divide-by-zero such as `w_(W/0)` — makes that token invalid and it is dropped, while the rest of the URL still builds. Referencing an alias forces a live measurement even when other sizing tokens are explicit.
A dropped token is a different outcome from a stalled element. A literal `/0` in the expression text drops the one token; an alias that resolves against a zero-height box does **not** drop — it triggers the silent stall in the warning below.
Do not put a `W`/`H` alias on an element that ends up in compatibility measurement. Compat sizes on width only and reports a height of **0**, so any alias needing a height waits for one that never arrives — the element stalls silently in a waiting state and never loads, with no `ar:error`.
This happens two ways: setting [`data-ar-measure="compat"`](#when-do-i-need-data-ar-measure) directly, **and** the automatic switch after **3** consecutive zero-size measurements — so an alias element inside a zero-size container can fall into compat on its own. Give alias-bearing elements a reliable box (explicit `width`/`height` or a sized ancestor), or use explicit token values instead of aliases.
## How does `data-ar-intrinsic` cap upscaling?
`data-ar-intrinsic` tells the runtime the source's real dimensions, as `"widthxheight"`.
```html theme={null}
```
It prevents upscaling past the source, caps how many variants can be generated, preserves the source aspect ratio when the cap engages, and improves cache reuse. Set it whenever you know the source size.
`width`/`height` and `data-ar-intrinsic` are not the same thing, even though HTML normally treats `width`/`height` as an image's intrinsic size. Here `width` and `height` (or a CSS `aspect-ratio`) are **layout hints** — the display box the browser reserves, which the runtime measures to pick a delivery width. `data-ar-intrinsic` is the **source's real pixel size**, used only to cap upscaling. An **800×600 px** display box of a **1600×1200 px** source carries `width="800" height="600"` and `data-ar-intrinsic="1600x1200"`.
## How do I override the width step per element?
`data-ar-step` overrides the global [`step`](/docs/native/configuration) for one element. Use it to give a hero image tighter sizing than a dense grid on the same page:
```html theme={null}
```
## How do I load an image immediately?
`data-ar-eager` skips visibility-based lazy loading, so the image loads as soon as the runtime processes it. Use it for above-the-fold images.
```html theme={null}
```
`data-ar-eager` skips lazy loading but does not solve LCP preload discovery — the browser cannot see the source at parse time. For the largest hero image, `data-ar-eager` is not the fix: hand-build the delivery URL and `` it, and do not add a real `src` next to `data-ar-src` (that double-fetches the image). See the [hero pattern](/docs/native/hero).
## How do I activate a group together?
`data-ar-view` on a container loads every marked descendant together the moment the container becomes visible, instead of each child activating on its own. Use it for galleries and sliders, where the whole group should appear at once.
```html theme={null}
```
## When do I need `data-ar-measure`?
`data-ar-measure="compat"` forces the compatibility measurement path, which derives width from an ancestor element instead of the element's own box. Set it only when an image reports a zero size under its normal layout — for example, inside a container the runtime cannot measure directly. In compat mode the runtime sizes on width alone.
The runtime also switches to compat automatically after **3** consecutive zero-size measurements of a visible element, so you only need to set this attribute when you want compat from the first load.
## Next steps
The script-URL parameters that set the defaults these attributes override.
Every raw token you can combine with `*`.
Add the script and load your first image.
How the delivery layer picks format, width, and quality.
```
To optimize a remote image, pass a full `https://` URL. The runtime routes it through Autorender's remote fetch:
```html theme={null}
```
```
`data-ar-eager` skips lazy loading but does not solve LCP preload discovery — the browser cannot see the source at parse time. For the largest hero image, `data-ar-eager` is not the fix: hand-build the delivery URL and `` it, and do not add a real `src` next to `data-ar-src` (that double-fetches the image). See the [hero pattern](/docs/native/hero).
## How do I activate a group together?
`data-ar-view` on a container loads every marked descendant together the moment the container becomes visible, instead of each child activating on its own. Use it for galleries and sliders, where the whole group should appear at once.
```html theme={null}
