---
url: /guide/autoloading.md
---
# Autoloading
`@studiometa/ui` ships a declarative autoloader entry. You import one side-effect module. The [`@studiometa/js-toolkit`](https://js-toolkit.studiometa.dev) autoload runtime then finds components from their `data-component` attribute and loads each component's JavaScript when it is needed.
The autoloader works the same way with a bundler and from a CDN. The same markup runs in a bundled application, a content site, a prototype, or a CMS template. The `@studiometa/ui/autoload` entry ships JavaScript only — no Twig templates and no stylesheets. Read [Limitations](#limitations) before you use it in an application.
For a no-build setup, load the entry from an ESM CDN such as [esm.sh](https://esm.sh). esm.sh serves any npm package as native ES modules and resolves the `@studiometa/js-toolkit` peer dependency. The examples below use esm.sh.
## Quick start
Add a module script. Import the `@studiometa/ui/autoload` entry. The import registers the `@studiometa/ui` manifest and starts discovery. There is nothing more to call.
```html
```
The runtime scans the document for `data-component` tokens, imports the matching modules, and registers them with the [js-toolkit](https://js-toolkit.studiometa.dev) runtime. The declarative contract (`data-component`, `data-ref`, `data-option-*`) is the same one that [Declarative runtime](/guide/concepts/declarative-runtime) describes.
Pin an exact version in production. See [Version pinning](#version-pinning).
## Activate a package
Import one side-effect entry for each component package you use. Each import registers that package's manifest with the shared runtime.
```html
```
The same entries resolve from `node_modules` when you install the packages and let your bundler resolve them:
```js
import '@studiometa/ui/autoload';
import '@studiometa/ui-mapbox/autoload';
import '@studiometa/ui-motion/autoload';
```
Import the entries at the top of one module. The manifests register before the runtime starts, so they join into one loader over the composed set. Import `@studiometa/ui-mapbox/autoload` only when you use the Mapbox family — see [Mapbox integration](#mapbox-integration) — and `@studiometa/ui-motion/autoload` only when you use [Motion](#motion-integration).
Every component on the page must resolve to one `@studiometa/js-toolkit` runtime. `@studiometa/ui`, `@studiometa/ui-mapbox` and `@studiometa/ui-motion` share the same `@studiometa/js-toolkit` peer, so one pin on that peer resolves the whole set.
### Version pinning
A version reference follows the package's npm tags and semver ranges:
```html
```
Pin an exact version in production. An exact-version URL is immutable and stays cached the longest, and it makes every entry on the page resolve to the same version. A versionless URL and `@latest` follow the latest stable release.
## Loading strategies
Each component has a default loading strategy in its manifest. Override it per element with `data-load`. There are four strategies:
| Strategy | The component loads when… |
| ------------- | -------------------------------------------------------------------------------------------- |
| `eager` | the runtime starts. |
| `visible` | the element is near the viewport (200px margin, `IntersectionObserver`). Default for Mapbox. |
| `idle` | the browser is idle (`requestIdleCallback`, 2-second timeout). |
| `interaction` | the first `pointerover`, `pointerdown`, or `focusin` on the element. |
```html
Loads on hover, touch, or focus
```
When a browser API is not available, the strategy falls back to eager loading.
The runtime resolves the strategy in this order:
1. An [eager ``](#eager-components) declaration. It always wins.
2. A valid `data-load` attribute. An invalid value logs a warning and uses the manifest default.
3. The manifest default.
### Eager components
Make a component load and mount at once, whatever its strategy, with a `` element:
```html
```
The `content` is a comma-separated list of tokens. Several metas concatenate. The runtime trims whitespace and drops empty and duplicate tokens. It ignores an unknown token and logs a warning.
## Component discovery
The runtime scans the document at startup and then observes it with a `MutationObserver`. It discovers:
* **Initial markup** — every `[data-component]` present when the script runs.
* **Added subtrees** — elements inserted after startup.
* **Multiple tokens** — space-separated values such as `data-component="Action Timer"`.
The runtime imports and registers each token once for the whole document. When a component registers, it also registers the child components it exposes. For example, `Accordion` brings in `AccordionItem`, so nested families work without a list of every child.
The runtime cleans up observers and listeners when an element leaves the DOM. Discovery follows node insertion and removal, so the runtime does not observe a change to the `data-component` attribute of an element already in the DOM. Add or replace the element instead.
When `MutationObserver` is not available, the initial scan still runs, but the runtime does not discover added components.
## Programmatic API
The autoload runtime and its helpers live in `@studiometa/js-toolkit`. The `@studiometa/ui/autoload` entry is only the side-effect wrapper that registers the `@studiometa/ui` manifest; the programmatic API — `autoload`, `registerManifests`, `defineManifest`, and the glob adapters — is imported directly from `@studiometa/js-toolkit`. Use it to compose a subset of packages, to scope discovery to a `root` element, or to build your own entry.
```js
import { autoload } from '@studiometa/js-toolkit';
import { manifest as uiManifest } from '@studiometa/ui/manifest';
const handle = autoload({ manifests: [uiManifest], eager: ['Action'] });
handle.stop(); // stop discovery
```
To autoload your own js-toolkit components, build a manifest from your component files with `defineManifest` and register it with `registerManifests`, both from `@studiometa/js-toolkit`. See the [js-toolkit autoload guide](https://js-toolkit.studiometa.dev) and the [autoload API reference](https://js-toolkit.studiometa.dev/api/autoload) for every export.
## Manual imports
You can also import components directly from the CDN, without the autoloader. This suits a script that builds components itself.
```js
import { Action, Modal } from 'https://esm.sh/@studiometa/ui@1.10.0'; // the whole surface
import { Action } from 'https://esm.sh/@studiometa/ui@1.10.0/Action'; // one component
```
Manual imports and the autoloader do not conflict, while every import on the page resolves to one js-toolkit runtime. Pin the same version everywhere.
## Mapbox integration
Mapbox components load like any other component, but the autoloader does not bundle `mapbox-gl`. You provide it. This keeps you in control of the Mapbox version and its Web Worker.
Declare an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) before the autoload script. Point the bare specifiers at a source of your choice. Add the geocoder entry only when you use `MapboxGeocoder`.
```html
```
Load the Mapbox stylesheet yourself, and the geocoder stylesheet only when you use `MapboxGeocoder`. Give each map a valid access token through its `data-option-map-options`. Mapbox components default to the `visible` strategy, so the map code loads when a map nears the viewport.
You own the `mapbox-gl` module, so its Web Worker is same-origin and a strict Content Security Policy works. When you load `mapbox-gl` from a CDN that builds its worker from a `blob:` URL, allow it: `Content-Security-Policy: worker-src blob:;`.
## Motion integration
The `Motion` component loads like any other component, but the autoloader does not bundle the [`motion`](https://motion.dev) library. You provide it through an import map, which keeps you in control of the Motion version:
```html
```
The component resolves `motion` lazily the first time an animation is built. In a bundled build you can inject a specific entry — such as the smaller `motion/mini` — with `provideMotion()`; see the [Motion JS API](/reference/items/Motion/js-api#providing-the-motion-dependency).
## Shopify integration
Most Shopify components autoload as they do in a bundled build. `FetchShopifyPartial` is the exception. The `@shopify/partial-rendering` adapter is not resolved in a no-build setup, so the component logs a diagnostic and falls back to the base [`Fetch`](/reference/items/Fetch/) behavior. Use a bundled build when you need partial rendering.
## Diagnostics
The runtime logs warnings under the `[@studiometa/js-toolkit/autoload]` prefix for recoverable conditions: a conflicting runtime version, an unknown token, an unknown eager component, an invalid `data-load` value, an invalid manifest strategy, or an unavailable browser API.
When a component fails to import or register, the runtime logs an error and dispatches a bubbling `js-toolkit:error` `CustomEvent` on the document element. Its `detail` carries the `token`, the `stage` (`import` or `registration`), and the `error`:
```js
document.addEventListener('js-toolkit:error', (event) => {
const { token, stage, error } = event.detail;
console.error(`Component ${token} failed at ${stage}:`, error);
});
```
esm.sh serves a source map with every asset, so developer tools show the original sources. The autoloader targets ES2020 module browsers (Chrome 63+, Firefox 67+, Safari 11.1+, Edge 79+).
## Limitations
A no-build install trades flexibility for a zero-build setup. Its constraints are deliberate:
* **One runtime version per page.** Several imports of the entries are safe; they share one runtime. Two different `@studiometa/js-toolkit` autoload runtimes cannot coexist — the second activation warns and does nothing. Pin one version.
* **One js-toolkit runtime.** Every component on the page must resolve to one `@studiometa/js-toolkit` runtime. Do not mix CDN components with a separate npm build that bundles its own copy.
* **No `data-component` mutation.** The runtime observes inserted and removed nodes only.
* **No Shadow DOM.** Components own standard light-DOM elements.
* **No templates or stylesheets.** No Twig, no `data-mount`, and no CSS — including no Mapbox CSS.
* **ES2020 module browsers only.**
* **Mapbox is not provided.** You supply `mapbox-gl` and its CSS through an import map.
* **Motion is not provided.** You supply `motion` through an import map.
* **Shopify partial rendering is excluded.** `FetchShopifyPartial` falls back to base `Fetch`.
## Next steps
* [js-toolkit autoload guide](https://js-toolkit.studiometa.dev) — autoload your own components.
* [autoload API reference](https://js-toolkit.studiometa.dev/api/autoload) — every export.
* [Declarative runtime](/guide/concepts/declarative-runtime) — the `data-component` / `data-option-*` contract.