AsyncBlock
One resource's four states: idle (no permission URL) → nothing; loading → the skeleton, aria-busy; error → the reason and Retry (reload); ready → the children, or empty when isEmpty(data) holds.
import { AsyncBlock } from '@ergasti/bricks';Examples
Four states
AsyncBlock takes a resource state (useResource returns one): a skeleton while loading, an error with Retry, the empty text, then your render function.
Code
import { AsyncBlock, Skeleton, type ResourceState } from '@ergasti/bricks';
interface Totals { sales: string }
function States() {
const reload = () => {};
const loading: ResourceState<Totals> = { status: 'loading', reload };
const failed: ResourceState<Totals> = { status: 'error', error: { status: 500, message: '' }, reload };
const empty: ResourceState<Totals | null> = { status: 'ready', data: null, reload };
const ready: ResourceState<Totals> = { status: 'ready', data: { sales: 'EGP 184,300' }, reload };
const skeleton = <Skeleton shape="rows" count={2} />;
return (
<div style={{ display: 'grid', gap: 16, maxWidth: 360 }}>
<AsyncBlock state={loading} skeleton={skeleton}>{() => null}</AsyncBlock>
<AsyncBlock state={failed} skeleton={skeleton}>{() => null}</AsyncBlock>
<AsyncBlock state={empty} skeleton={skeleton} empty="Nothing here yet" isEmpty={(data) => data === null}>{() => null}</AsyncBlock>
<AsyncBlock state={ready} skeleton={skeleton}>{(data) => <b>Sales: {data.sales}</b>}</AsyncBlock>
</div>
);
}Skeleton shapes
line, rows, tile and hero match the shapes they stand in for, so the page does not jump when data arrives.
Code
import { Skeleton } from '@ergasti/bricks';
function Shapes() {
return (
<div style={{ display: 'grid', gap: 12, maxWidth: 420 }}>
<Skeleton shape="line" />
<Skeleton shape="rows" count={3} />
<div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 12 }}>
<Skeleton shape="tile" />
<Skeleton shape="hero" />
</div>
</div>
);
}Props
Prop
Type
Labels
Every word this component draws, in both languages. Override one per component and language with BricksProvider labels under the key asyncBlock, or with the component's own prop where it has one. A {name} is a value the component fills in.
| Key | English | Arabic |
|---|---|---|
retry | Retry | جرّب تاني |
Design guidance
How the BRICKS design system uses AsyncBlock. Written in docs/content/components/AsyncBlock.md; the props above are read from the code, which wins where the two disagree.
Draws a ResourceState from useResource: a skeleton while loading, an alert with Retry on error, an empty state, or your content with the data; use it around any block that loads its own data.
It removes the four-way if from every data block and keeps the states consistent across both dashboards: idle (no permission URL) renders nothing; first load shows a skeleton shaped like the content (never a lone spinner); an error shows the server's message, or a status-based sentence, with Retry; ready renders children(data), or empty when isEmpty(data) holds. A reload keeps the previous data on screen. Skeleton is exported with it.
Anatomy
- Loading wrapper:
.kit-async-load,aria-busy="true", holding yourskeleton(Skeletonshapes). - Error box:
.kit-async-err,role="alert": the reason text and a smallButton"Retry" that callsstate.reload. - Empty: your
emptynode, drawn as given. - Content:
children(data).
Skeleton shapes (.kit-skel--line | rows | tile | hero): grey --track blocks with the content's radius, aria-hidden.
Variants
| State / shape | Look | When to use |
|---|---|---|
Skeleton shape="line" | One text-height bar | Titles, a single figure. |
shape="rows" | Row-height bars (count of them) | Lists and tables. |
shape="tile" | Tile-sized block (--r-lg) | KPI / metric tiles. |
shape="hero" | Hero-card block (--r-xl) | The wallet hero. |
States
| State | Trigger | Renders |
|---|---|---|
| Idle | state.status === 'idle' | null |
| Loading (first) | 'loading' and data === undefined | skeleton, aria-busy |
| Reloading | 'loading' with previous data | the children with old data |
| Error | 'error' | error.message, else httpError(error.status) (403 says no access), + Retry |
| Empty | ready and isEmpty(data) and empty given | empty |
| Ready | 'ready' | children(data) |
Types
Skeleton: shape: 'line' | 'rows' | 'tile' | 'hero' (required), count?: number (default 1).
ResourceState<T> (state): { status, data?, error?, reload } from useResource / usePaged.
Usage
const state = useResource<TopCreator[]>(urls.topCreators);
<Card title="Top creators this month">
<AsyncBlock
state={state}
skeleton={<><Skeleton shape="line" /><Skeleton shape="rows" count={5} /></>}
isEmpty={(rows) => rows.length === 0}
empty={<EmptyView title="No sales yet this month" />}
>
{(rows) => <RankList label="Top creators this month" items={rows.map(toRankItem)} />}
</AsyncBlock>
</Card>// The 4-up KPI grid while loading
<AsyncBlock state={kpis} skeleton={<KpiGrid><Skeleton shape="tile" count={4} /></KpiGrid>}>
{(k) => <KpiGrid>{k.map((x) => <KpiCard key={x.key} {...x} />)}</KpiGrid>}
</AsyncBlock>Where it appears
- In the v3 mocks: not a visible region of its own; it is the loading / error / empty wrapper for any data block (the mocks draw one-skeleton loading,
.skel). - Library only: the kit gallery wraps a
KeyValuelist in it. List blocks (ActivityLog,BundleGrid,MessageHistoryList) implement the same states through their ownstatusprop.
Guidelines
Do
- Shape the skeleton like the content (rows for a list, tiles for a grid).
- Give an
emptynode with a next step whenever an empty list is possible.
Don't
- Don't show a spinner-only skeleton.
- Don't render your own error UI inside
children; let the block handle it.
RTL and Arabic
- Retry and the status sentence come from copy in Arabic with
language="ar"or the provider. Skeletons are direction-neutral.
Tokens
--track (skeleton), --r-lg, --r-xl, --rasp-50 and --bad (error box).
Accessibility
- Loading wrapper has
aria-busy="true"; skeleton blocks arearia-hidden. - Error is
role="alert". It mounts together with its text; most screen readers read an alert that appears, but this is not guaranteed for every one. Retry is a real button, so the error can also be found by Tab. - Skeleton shimmer stops under
prefers-reduced-motion.
Found in the source
- Roles in the markup:
alert. - ARIA attributes set:
aria-hidden,aria-busy.
Read from the component's source and tests. See Accessibility for the patterns the library follows.
Related
useResource,usePaged: produce thestate.EmptyView: a ready-made empty state forempty.DialogSkeleton: the loading body forModal/Drawer.
See also: Button · Skeleton · Banner · ToastRegion
Source
src/kit/patterns/AsyncBlock.tsx (line 17) on GitHub.