---
name: directives
description: >
Built-in client directives: client:visible (IntersectionObserver, rootMargin),
client:media (matchMedia query), client:idle (requestIdleCallback),
client:defer (setTimeout delay), client:interaction (mouseenter/touchstart/focusin).
Directives resolve sequentially — visible → media → idle → defer → interaction → custom.
Per-element value overrides. Empty client:media warning.
type: core
library: vite-plugin-shopify-theme-islands
library_version: "1.1.0"
sources:
- Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
- Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
---
## Setup
Add one or more directives as HTML attributes on any custom element:
```html
```
No JS changes needed — the runtime reads these attributes during DOM walk.
## Core Patterns
### Combining directives — sequential resolution order
Directives resolve in a fixed order: `visible → media → idle → defer → interaction → custom`. Each condition is only evaluated after the previous one has passed.
```html
```
Combined directives are AND-latched. The island loads only after every condition resolves. There is no OR mode.
### Per-element value overrides
```html
```
The attribute value overrides the globally configured default for that element. Other elements are unaffected.
### `client:defer` without a value uses the global default
```html
```
An empty `client:defer` attribute is NOT zero — it falls back to the configured `defer.delay` (default 3000ms).
### `client:interaction` with no value uses the default events
```html
```
An empty `client:interaction` attribute silently uses the configured default events — no warning is emitted (unlike `client:media`).
### Changing built-in directive defaults globally
```ts
// vite.config.ts
shopifyThemeIslands({
directives: {
visible: { rootMargin: "0px" },
defer: { delay: 5000 },
interaction: { events: ["mouseenter"] },
},
});
```
## Common Mistakes
### HIGH `client:media=""` skips the media check entirely
Wrong:
```html
```
Correct:
```html
```
An empty `client:media` value emits a console warning and skips the media check — the island loads immediately. Provide a valid media query string.
Source: src/runtime.ts — `if (query === "")` branch
### HIGH Multiple directives are AND, not OR
Wrong assumption:
```html
```
Correct understanding:
```html
```
The runtime awaits each directive sequentially. There is no way to express OR semantics with built-in directives — use a custom directive for that.
Source: src/runtime.ts — loadIsland sequential awaits
### MEDIUM `client:defer` without value ≠ immediate load
Wrong:
```html
```
Correct:
```html
```
`client:defer` with no value uses the global `defer.delay` default (3000ms). `parseInt("", 10)` produces `NaN`, which the runtime replaces with the configured default.
Source: src/runtime.ts — `const ms = Number.isNaN(raw) ? deferDelay : raw`
### MEDIUM Per-element visible value replaces rootMargin, not adds to it
Wrong:
```html
```
Correct:
```html
```
The attribute value is passed directly to `IntersectionObserver` as `rootMargin`, fully replacing the global default.
Source: src/runtime.ts — `await visible(el, visibleAttr || rootMargin, threshold, pendingCancellable)`
### HIGH Directive attribute typo — island loads without condition
Wrong:
```html
```
Correct:
```html
```
Directive attributes are case-sensitive. An unrecognised attribute is silently ignored — the island loads immediately as if no directive were set. No warning is emitted. Check for typos if an island activates earlier than expected.
Source: src/runtime.ts — runtime checks exact attribute names from plugin config
### HIGH Agent uses default attribute name when developer has configured a custom one
Wrong:
```html
```
Correct:
```html
```
When `directives.visible.attribute` (or any directive's `attribute` option) is overridden in `vite.config.ts`, all Liquid templates must use the configured name. The default `client:*` names no longer apply. Always read `vite.config.ts` to check for overridden attribute names before writing directives in Liquid.
Source: src/index.ts:DirectivesConfig — `attribute` field per directive; src/runtime.ts reads configured attribute names at runtime