Deferred
A region that lazily loads its content on visibility, with skeleton and error states.
Installation
Included in poetry-ui — available as
poetry_deferred
the moment you've installed Poetry,
with no per-component step. To own the source and edit it, copy it into your app:
bin/rails g poetry:add deferred
Default
This section failed to load.
<%# Lazy region: the Skeleton holds the box until the frame scrolls into
view, then the fragment replaces it. Guide with the full story
(error/retry, Tabs + HoverCard defer:): /deferred. %>
<div class="w-full max-w-md">
<%= poetry_deferred(src: deferred_fragment_path, id: "component-demo-activity") %>
</div>
API
Poetry::Ui::Deferred::Component — options are
constructor keywords (the poetry_* helper forwards them);
slots are composed inside the block. Generated from the gem's source documentation.
| Option | Type | Details | Description |
|---|---|---|---|
| loading: | Symbol | defaults to :lazy |
:lazy fetches when the frame becomes visible; :eager fetches right after paint. |
| src: | String | required | The URL to fetch - required; rendering without it raises. |
Styling
Every part carries a stable data-slot attribute — target
[data-slot=…] from your own CSS to restyle it. State rides
data attributes on the parts below. This contract is verified against rendered DOM in CI.
| Part | Description |
|---|---|
| [data-slot=deferred] | The <turbo-frame> root - src is armed at connect(); failure is a state reflected here, never silent blankness |
| [data-slot=deferred-error] | The retryable error card, stamped into the frame from the slotted <template> on failure |
State attributes
| Part | Attribute | Condition | Values |
|---|---|---|---|
| deferred | data-error | a frame fetch failed (error response, missing frame, or network error) - the controller stamps the error card; retry clears it | — |
Wiring
The Stimulus surface each element carries — declared in the component, verified against rendered DOM in CI. Bare actions fire on the element's default event.
| Element | Controller | Wiring |
|---|---|---|
| root | poetry--core--deferred | registers · value src |
| placeholder | poetry--core--deferred | target placeholder |
| error_template | poetry--core--deferred | target error |
| retry | poetry--core--deferred | retry on click |