DataState

Code

import { Button, DataState } from "@fadymondy/nasaq/web";declare const query: { isLoading: boolean; error: Error | null; data: { id: string; name: string }[]; refetch(): void };export function Projects() {  return (    <DataState      loading={query.isLoading}      error={query.error}      onRetry={query.refetch}      empty={query.data.length === 0}      labels={{ emptyTitle: "No projects yet" }}      emptyAction={<Button variant="primary">New project</Button>}    >      <ul>{query.data.map((p) => <li key={p.id}>{p.name}</li>)}</ul>    </DataState>  );}

Loading & States · beta

Live examples and controls: DataState in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/data-state.json

Wraps a list, table or chart that loads data and picks the right state for you. Pass what your fetch knows (loading, error, empty…) and the content as children; only one thing renders.

When to useCopy Anchor Link

• Any view that fetches: a table page, a dashboard card, a side panel list.
• When the same view can be signed out (401), down (503) or failing for another reason.

When not to useCopy Anchor Link

• A whole failed page or route: use ErrorPages.
• A single state on its own: use LoadingState, EmptyState or ErrorState from States.

ImportCopy Anchor Link

import { DataState, ServiceUnavailable } from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"

Quick startCopy Anchor Link

import { Button, DataState } from "@fadymondy/nasaq/web";

declare const query: { isLoading: boolean; error: Error | null; data: { id: string; name: string }[]; refetch(): void };

export function Projects() {
  return (
    <DataState
      loading={query.isLoading}
      error={query.error}
      onRetry={query.refetch}
      empty={query.data.length === 0}
      labels={{ emptyTitle: "No projects yet" }}
      emptyAction={<Button variant="primary">New project</Button>}
    >
      <ul>{query.data.map((p) => <li key={p.id}>{p.name}</li>)}</ul>
    </DataState>
  );
}

AnatomyCopy Anchor Link

DataState                       data-slot="data-state" on the state shown
├─ loading       → loadingFallback, or LoadingState with skeleton rows
├─ unauthorized  → EmptyState with a sign-in button
├─ unavailable   → ServiceUnavailable with retry
├─ error         → ErrorState with the message and retry
├─ empty         → EmptyState with emptyAction
└─ children      when none of the above

The first true state wins, in that order.

APICopy Anchor Link

DataState

ServiceUnavailable: the EmptyState props plus onRetry, an optional title and labels. The "can't reach the service" state on its own.

AccessibilityCopy Anchor Link

• Loading is announced through LoadingState (role="status"). Errors use role="alert".
• Retry and sign-in are real buttons or links with visible text.

RTL & i18nCopy Anchor Link

• English and Arabic strings follow the Nasaq locale. The states are centred, so they read the same in both directions.

Styling & tokensCopy Anchor Link

• Built on States and Button. Target [data-slot="data-state"].

Do / Don'tCopy Anchor Link

• Do pass onRetry whenever the request can be repeated.
• Do keep empty for "no rows" and error for "request failed"; don't show an empty table after a failure.
• Don't nest DataState inside DataState for the same request.

RelatedCopy Anchor Link

• States
• ErrorPages

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-loading-states-data-state--docs