AvalonAvalon
GitHub

island prop

Complete reference for the island prop API.

Type definition

interface IslandProp {
  condition?: IslandCondition;
  id?: string;
  persist?: string | true;
  conditionArg?: string;
  ssr?: boolean;
}

type IslandCondition =
  | 'on:client'
  | 'on:visible'
  | 'on:interaction'
  | 'on:idle'
  | `media:${string}`
  | `on:${string}`;  // custom directives

Properties

PropertyTypeDefaultDescription
conditionIslandCondition'on:client'When the island hydrates or mounts
idstringAuto-generatedStable identifier for state persistence
persiststring | true—Keep the live instance across client navigations. true uses the component source path as the key. Qwik is skipped.
conditionArgstringundefinedArgument passed to custom directives
ssrbooleantrueRender HTML on the server. false skips that: Avalon emits an empty placeholder and mounts the component in the browser. Props are still serialized.

Valid condition values

ValueTrigger
on:clientImmediately on page load
on:visibleElement enters the viewport
on:interactionFirst click or hover
on:idleBrowser idle time
media:(query)CSS media query matches
on:delayAfter a timeout (ms)
on:scrollPage scrolled past threshold (px)
on:eventCustom DOM event fires
on:matchMedia query matches via directive
on:<custom>Any registered custom directive

Usage

<Counter island={{ condition: 'on:interaction' }} />

<Widget island={{ condition: 'on:delay', conditionArg: '2000' }} />

<Counter island={{ condition: 'on:client', id: 'hero-counter' }} />

<ThemeToggle island={{ condition: 'on:idle', persist: 'theme-toggle' }} />

<Chart island={{ ssr: false }} userId={user.id} />

<Map island={{ ssr: false, condition: 'on:visible' }} />

Props must be serializable to JSON — they are embedded in the HTML as a data attribute for hydration.

ssr: false skips the component on the server. It may use window / document in its body. Users without JavaScript see an empty placeholder for that island. on:visible still needs a sized host (the placeholder is display: block, but has no intrinsic height until it mounts).

See also