Components
Components for deferring content in the HTML shell. Imported from @vincle/flow.
Defer#
Renders a placeholder holding fallback, and patches it later with its
children:
import { Defer } from "@vincle/flow";
async function HeavyDashboard() {
const data = await fetch("https://api.example.com/dashboard");
const json = await data.json();
return <pre>{JSON.stringify(json, null, 2)}</pre>;
}
// fallback is shown in the shell immediately.
<Defer target="dashboard" fallback={<p>Loading dashboard…</p>}>
<HeavyDashboard />
</Defer>;
children is plain JSX, a promise, or an AsyncIterable (one patch per
item), or a factory (signal: AbortSignal) => … returning any of those. The
signal aborts when the request is cancelled or the timeout expires.
target is optional: without it, Vincle generates the placeholder id.
Props:
| Prop | Type | Default | Description |
|---|---|---|---|
target |
string |
Generated id | Optional placeholder id; match a Slot name to fill it |
fallback |
JSX.Element |
N/A | Content rendered in the placeholder |
children |
JSX.Element | string | ((signal: AbortSignal) => JSX.Element) | AsyncIterable<JSX.Element> | ((signal: AbortSignal) => AsyncIterable<JSX.Element>) |
N/A | Content: plain JSX, a factory, or an async iterable |
merge |
"replace" | "update" | "append" | "prepend" | "before" | "after" | "morph" |
"replace" |
How content applies to the target |
timeout |
number |
N/A | Per-fragment render timeout in ms |
onError |
(error: unknown, info: FlowErrorInfo) => JSX.Element | void |
N/A | Per-fragment error handler |
Slot#
A placeholder declared apart from its Defer: typically a layout reserving a
spot that a page fills later, by matching target to name. Its children are
shown until the matching Defer patches them.
import { Slot, Defer } from "@vincle/flow";
async function LiveComments() {
const res = await fetch("https://api.example.com/comments");
const comments: Array<{ id: string; text: string }> = await res.json();
return (
<ul>
{comments.map((c) => (
<li key={c.id}>{c.text}</li>
))}
</ul>
);
}
function Page() {
return (
<html>
<body>
<Slot name="comments">
<p>Loading comments…</p>
</Slot>
<Defer target="comments" timeout={5000}>
<LiveComments />
</Defer>
</body>
</html>
);
}
The Slot is the placeholder: its Defer emits none of its own, wherever the
two sit in the page.
Props:
| Prop | Type | Default | Description |
|---|---|---|---|
name |
string |
N/A | Fragment id, required |
children |
VNode |
N/A | Fallback content rendered immediately in the shell |
Style / Script: asset emission#
<Style> and <Script> emit their tag where they stand, once per name: the
first occurrence in the document wins, later ones render nothing, even when a
later occurrence finishes rendering first (siblings are concurrent). Only the
winning occurrence's content factory is evaluated; it runs with the Provider
and Scope context of its own position.
import { Style, Script } from "@vincle/flow/components";
const Page = () => (
<>
<Style name="page.css" media="screen">
{`.hero { color: red; }`}
</Style>
<Script name="page.js" defer src="/page.js" />
<main>…</main>
</>
);
Style props:
| Prop | Type | Default | Description |
|---|---|---|---|
name |
string |
N/A | Asset id, required, dedup key |
media |
string |
N/A | media attribute |
children |
string | (() => Awaitable<string>) |
N/A | CSS text, evaluated only if this occurrence emits |
Script props:
| Prop | Type | Default | Description |
|---|---|---|---|
name |
string |
N/A | Asset id, required, dedup key |
src |
string |
N/A | src attribute |
module |
boolean |
false |
Sets type="module" |
defer |
boolean |
false |
Sets the defer attribute |
children |
string | (() => Awaitable<string>) |
N/A | Inline JS, evaluated only if this occurrence emits |
Fragment files written by emitFragments carry no <style>/<script>: the
shell that includes them already has the assets.