` until the reader reaches it, then a `Frame` for `src` with `fallback` (or `children`) covering the request. A loaded frame keeps its content when it scrolls away or its container closes.
- `src`: where the content is fetched from.
- `loadOn`: `"approach"` (the default) loads once the frame nears the viewport, through an [`IntersectionObserver`](https://developer.mozilla.org/docs/Web/API/IntersectionObserver); `"open"` loads the first time the closest `
`, `` or `[popover]` around it opens, or at once when it is already open.
- `rootMargin`: how far around the viewport an approaching frame starts its fetch, in `rootMargin` syntax. Defaults to `"320px 0px"`.
- `fallback`: what stands in while the request is in the air. Defaults to `children`.
- `url` and `parentUrl`: the address of the page the frame holds, and of the page it sits in. Given both, the address bar's entry is replaced with `url` once the frame's top passes the top tenth of the viewport, and with `parentUrl` when the reader scrolls back above it, so a reload resumes where they had read to. Nested frames settle on the deepest one reached.
- `sitsAbove`: marks a frame placed above content the reader already sees. It loads once the reader has scrolled past it and come back, and scrolls the page by what it adds so the content under their eyes stays put.
- `opener`: with `loadOn="open"`, the `id` of a link that, once script runs, opens the frame's container and stays on the page.
### Types
#### `LazyFrameProps`
The props above, declared as a `type` so they satisfy the serializable props a client entry is checked against.
#### `LazyFrameContent`
What `children` and `fallback` accept: one element, text, a number, a boolean, or `null`.
## Pattern: A list that pages in both directions
Each page renders its rows between two frames: one above for the newer page, one below for the older. Frames nest, since each fetched page carries its own pair, and the address bar follows the reader through them.
```tsx
import { LazyFrame } from "@sdxc/lazy-frame/ui";
interface Page {
url: string;
newer: string | null;
older: string | null;
rows: { id: string; title: string }[];
}
function frameOf(url: string) {
return `${url}${url.includes("?") ? "&" : "?"}frame`;
}
function PostsPage() {
return ({ page }: { page: Page }) => (
);
}
```
## Pattern: Details behind a disclosure or popover
A `` or a `[popover]` loads its body the first time it opens, so a page of collapsed sections fetches only the ones the reader expands. The `fallback` covers the request; the `children` stay the scriptless link.
```tsx
import { LazyFrame } from "@sdxc/lazy-frame/ui";
Changelog
Read the changelog
Profile
;
```
## Pattern: Below-the-fold sections fetched early
A long page renders its first screen on the server and leaves heavier sections to frames. A wider `rootMargin` starts each fetch further ahead, so the content is in place by the time the reader scrolls to it.
```tsx
import { LazyFrame } from "@sdxc/lazy-frame/ui";
function ProductPage() {
return ({ id }: { id: string }) => (
Product
Read the reviews
See related products
);
}
```
## Versioning
Releases are dated rather than semantic. A version is the UTC date it was published, written `YYYY.M.D`, so `2026.9.4` is the release from 4 September 2026. At most one release goes out per day.
Those numbers say when, not what: a later date means a later release and carries no compatibility promise. Any release may change or remove an export.
Depend on one exact date, and move it when you are ready to take the change:
```json
{
"dependencies": {
"@sdxc/lazy-frame": "2026.9.4"
}
}
```
A caret or tilde range reads the date as major, minor and patch, so it accepts every later release in the same year. An exact version keeps the upgrade yours to schedule.
## License
MIT
## Author
[Sergio Xalambrí](https://sergiodxa.com)