<script> src. The runtime exposes a small handle at window.__AR_NATIVE__ (version, the parsed config, and destroy()), but every configuration value comes from the URL — see How do I tear down the runtime? for the handle.
Every parameter except
ws is optional. A typo in an optional parameter falls back to its default rather than disabling the runtime. ws is the exception: a missing or malformed ws logs a fatal error and disables the runtime.What are the parameters?
How does ws work?
ws is your workspace ID — the same public routing segment that appears in every Autorender delivery URL. It is required, and without a valid value the runtime logs a fatal error and stays disabled.
It is a public routing identifier, not a secret. Do not put an API key on the page; Autorender Native performs client-side delivery only.
How does max-dpr cap resolution?
max-dpr clamps the device pixel ratio the runtime multiplies into each requested width, so a 3× phone still requests at most 2× by default. The clamp trades a small amount of sharpness on very high-density screens for smaller files and higher cache reuse.
We recommend the default of 2 for most sites, because the visual gain from 3× is marginal while the file is roughly twice the bytes. Raise it to 3 only for detail-critical imagery such as product zoom.
How does step reduce requests?
step is the rounding increment for requested widths. The runtime multiplies each measured CSS width by the device pixel ratio, then rounds the result up to the next multiple of step. On a 2× screen a 396 px box needs 792 device px, which rounds up to w_800; a 398 px box needs 796 px and also requests w_800 — one variant, one request, instead of two.
This matters most while an element resizes. As a box grows during a window drag or a layout shift, the runtime fetches a new variant only when the width crosses a step boundary, so a larger step crosses fewer boundaries and fires fewer requests — raising step from 10 px to 50 px cuts resize requests by about 5×. The runtime never re-fetches when a box shrinks.
step accepts any integer from 1 to 512, and does not have to be a multiple of 10. Most sites never change it — the default of 10 px suits most layouts. Raise it to 50 on image-dense grids to cap the requests a resize can generate.
step and width bucketing act on two different layers, so one does not replace the other. step is request-side: it decides how many distinct widths the browser asks for as a box resizes. Width bucketing is cache-side: the delivery layer rounds each requested width up to a shared bucket so nearby widths reuse one cached file.
Bucketing happens after the request leaves the browser, so it cannot remove the requests step prevents. Set step to 1 and the browser fires a new request on nearly every pixel of a resize, even when the delivery layer returns the same cached image each time.
How does anticipation set the lazy-load lookahead?
anticipation is how far ahead of the viewport the runtime starts loading an image. It accepts three forms:
- a percentage of the viewport —
20%(the default) - an absolute pixel distance —
300px - a bare ratio —
0.2, equivalent to20%
How do I avoid CSS class name clashes?
The runtime marks every element it manages with a lifecycle class —ar-loading, ar-done, and ar-error on images, and ar-background-loading, ar-background-done, and ar-background-error on backgrounds. If your site already uses ar- class names for something else, set class-prefix to rename them:
acme-loading, acme-done, acme-error, and acme-background-*, leaving your own ar- styles untouched.
class-prefix must start with a lowercase letter and contain only lowercase letters, digits, and single hyphens, up to 32 characters — for example acme or acme-img. An invalid value falls back to the default ar. Only the CSS classes change; the data-ar-* attributes are fixed. See Events and classes for the full class list and how to style each state.
How do I turn on debug logging?
Adddebug=1 to log diagnostics to the browser console: missing or invalid configuration, invalid intrinsic values, rejected transform tokens, zero-size elements, and eager images with no parse-time src.
ws is missing. Leave debug off in production.
How do I tear down the runtime?
Callwindow.__AR_NATIVE__.destroy() to shut the runtime down completely — for example when a test harness tears down between cases, or when an embedded widget that started the runtime is removed and you are handing the page to another tool. It disconnects the three observers (IntersectionObserver, ResizeObserver, MutationObserver), so no further elements are measured, loaded, or upgraded.
destroy() stops future work only. It does not undo what already loaded: every processed element keeps its variant src and its lifecycle class (ar-done and the rest), and no original src is restored. There is no re-initialize or rescan — once destroyed, the runtime stays down for the life of the page, and re-adding the script tag does not restart it.
window.__AR_NATIVE__ is a minimal handle — version, the parsed config, and destroy() — not a full public API. There is no method to add, refresh, or re-scan elements. While the runtime is running, its MutationObserver discovers new nodes on its own, so a single-page app that swaps content into the live document is picked up automatically, with no call needed.Next steps
Attributes
Mark images, backgrounds, transforms, and view containers.
Introduction
What Autorender Native does and when to use it.
Automatic optimization
How the delivery layer picks format, width, and quality.
Events and classes
Style load states and hook into the image lifecycle.