Skip to Content
BBRICKSv0.7.4
KitFeedback

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.

asyncBlock
KeyEnglishArabic
retryRetryجرّب تاني

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

  1. Loading wrapper: .kit-async-load, aria-busy="true", holding your skeleton (Skeleton shapes).
  2. Error box: .kit-async-err, role="alert": the reason text and a small Button "Retry" that calls state.reload.
  3. Empty: your empty node, drawn as given.
  4. Content: children(data).

Skeleton shapes (.kit-skel--line | rows | tile | hero): grey --track blocks with the content's radius, aria-hidden.

Variants

State / shapeLookWhen to use
Skeleton shape="line"One text-height barTitles, 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

StateTriggerRenders
Idlestate.status === 'idle'null
Loading (first)'loading' and data === undefinedskeleton, aria-busy
Reloading'loading' with previous datathe children with old data
Error'error'error.message, else httpError(error.status) (403 says no access), + Retry
Emptyready and isEmpty(data) and empty givenempty
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 KeyValue list in it. List blocks (ActivityLog, BundleGrid, MessageHistoryList) implement the same states through their own status prop.

Guidelines

Do

  • Shape the skeleton like the content (rows for a list, tiles for a grid).
  • Give an empty node 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 are aria-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.

See also: Button · Skeleton · Banner · ToastRegion

Source

src/kit/patterns/AsyncBlock.tsx (line 17) on GitHub.

On this page