Data state

Preview

Local preview. It doesn't affect real accounts, environments, or run data.

Usage

• Wrap any content that waits for data in DataState, so loading, failure and emptiness never look the same. state says where the data stands; the content shows when it is ready, and stays under a caution when it is stale.
• loading draws a placeholder of placeholderHeight, so nothing moves when the data arrives. error says what failed, in message, with a retry when onRetry is set; after a retry focus moves to retryFocus, or the DataState itself. empty says why there is nothing, and what to do next.
• refreshing keeps the content, dimmed and busy, while new data comes, and announces it. Dashboard.Panel draws its body with DataState and shows its own spinner by the title.
• layout inline fits a line beside other text, block fills a card or a region, and page stands in for a whole page while there is none: its loading, error and empty notices centre in the page's room, and ready or stale content keeps its own layout.

• Don't decide the state from the data alone: an empty result and a failure both have no data. Take it from the request.
• Don't clear the content while it refreshes, or show zero for an error.
• Don't announce a page load as a failure; say what failed and what the reader can do.

Size: SizeProvider size="small" resizes the whole composition, including portals. The default size is Default. Size guidance and comparisons

Anatomy

Root(state, layout) → placeholder | message + retry | empty sentence | caution + content | content

Keyboard and accessibility

• The retry button is in the Tab order; Enter or Space retries.
• After a retry takes the button away, focus moves to retryFocus or the DataState, not the page.

Give each control a name that describes its purpose. Connect error messages to their controls, and signal state with more than color. Automated checks don't replace manual keyboard and assistive technology testing.

Example code

Shared components take their styles from design tokens. Each example sets its own composition and accessibility attributes. The calling screen defines callbacks, refs, and product data.

import { DataState } from '@surflane/ui'

<DataState
  state={query.isPending ? 'loading' : query.isError ? (query.data ? 'stale' : 'error') : query.data?.length ? 'ready' : 'empty'}
  refreshing={query.isFetching && !query.isPending}
  onRetry={() => query.refetch()}
  message={query.error?.message}
>
  <HoldingsTable rows={query.data} />
</DataState>

Key API

The table lists the common wrapper's main props. See the package type declarations for the full types.

Related tokens