UseIslandOptions
Defined in: react/src/useIsland.ts:54
Properties
Section titled “Properties”campaignId?
Section titled “campaignId?”
optionalcampaignId?:string
Defined in: react/src/useIsland.ts:55
enabled?
Section titled “enabled?”
optionalenabled?:boolean
Defined in: react/src/useIsland.ts:98
Skip the stream entirely (previews, storybook, reduced-motion policies).
fallback
Section titled “fallback”fallback:
object
Defined in: react/src/useIsland.ts:64
First paint. REQUIRED, and not merely encouraged: the doctrine has no skeleton state, so if the network is slow or the campaign is unreachable, this copy is what the viewer reads. A component with nothing here has nothing honest to render.
optionalbody?:string
optionalcta?:string
greeting?
Section titled “greeting?”
optionalgreeting?:string
headline?
Section titled “headline?”
optionalheadline?:string
holdMs?
Section titled “holdMs?”
optionalholdMs?:number
Defined in: react/src/useIsland.ts:118
How long the canvas holds blank waiting for the stream before fallback
paints. Defaults to COPY_HOLD_MS (2.5 s), and restarts once when the
stream proves it is alive, so the blank can last up to twice this.
The floor does not move: when the budget runs out your fallback paints,
whatever you set here. A shorter budget shows your own copy sooner and
takes the stream’s copy as the one permitted rewrite; a longer one gives a
slow connection more room to land adapted copy as the first thing read.
island
Section titled “island”island:
"cta"|"hero"
Defined in: react/src/useIsland.ts:57
optionalpin?:boolean
Defined in: react/src/useIsland.ts:107
Participate in page-level variant pinning (default true). Pinning exists
so sibling islands of one campaign cannot tell two different stories —
the hero and its CTA must come from one draw. Pass false for an island
that is MEANT to say something new for the same campaign (a mid-page
narrative card on a continuity page): it neither consumes the page’s
pinned variant nor writes its own draw back to the page.
serverRendered?
Section titled “serverRendered?”
optionalserverRendered?:boolean
Defined in: react/src/useIsland.ts:94
True when fallback was server-rendered and has therefore been on screen
since the page’s own first paint. Such copy is exempt from the hold —
blanking text a reader already has in front of them is the very thing the
hold exists to prevent.
When OMITTED, the hook detects it: on-screen means the component HYDRATED over server HTML (the Next.js “use client” case, where components still SSR) and the host element contains text — copy that has genuinely been in front of the viewer since the page’s first paint. A client-only mount is NOT on-screen: its fallback was committed by this very render and has not been read, so the hold arms and the canvas waits blank for the stream. An earlier revision counted any text present at stream-open time, which is every field of every client integration (the fallback always commits before the stream opens) — so the hold was unreachable and the fallback always painted ahead of the stream it was about to lose to. Pass the prop explicitly to override the detection in either direction.
Explicit or detected, on-screen means the same choreography: exempt
from the hold, and never typed over — live deltas buffer off-canvas and
the copy changes at most once, composed, at *-done. Copy a reader is
on is never retyped under their eyes; the typed entrance is reserved
for the blank canvas the hold paints.
sessionId?
Section titled “sessionId?”
optionalsessionId?:string
Defined in: react/src/useIsland.ts:96
Conversation session id, for copy continuity. Individual surfaces only.
surfaceId?
Section titled “surfaceId?”
optionalsurfaceId?:string
Defined in: react/src/useIsland.ts:56