Await

API reference for the Await component - handle asynchronous operations with built-in suspense and error boundaries.

Overview

The Await component provides a declarative way to handle asynchronous operations in React, with built-in support for Suspense and Error Boundaries. It automatically manages loading, success, and error states.

Import

import { Await } from "@zayne-labs/ui-react/common/await";
// or
import { AwaitRoot, AwaitSuccess, AwaitError, AwaitPending } from "@zayne-labs/ui-react/common/await";

Component Parts

Await.Root

The root component that wraps the promise handling logic

Await.Success

Renders when the promise resolves successfully

Await.Error

Renders when the promise rejects with an error

Await.Pending

Renders while the promise is pending

Await.Root

Props

promise · Promise<TValue> · required

The promise to await and resolve.

children · React.ReactNode | ((result: TValue) => React.ReactNode) · required

The content to render on success. Can be a render function that receives the resolved value.

fallback · React.ReactNode

Fallback UI to display while the promise is pending (used with Suspense).

errorFallback · React.ReactNode | ((props: ErrorFallbackProps) => React.ReactNode)

Fallback UI to display when the promise rejects (used with ErrorBoundary).

withSuspense · boolean · default: "true"

Whether to wrap the component with React Suspense.

withErrorBoundary · boolean · default: "true"

Whether to wrap the component with an ErrorBoundary.

asChild · boolean

When true, merges props into the child element instead of rendering a wrapper.

Await.Success

Props

children · React.ReactNode | ((result: TValue) => React.ReactNode) · required

The content to render when the promise resolves. Can be a render function that receives the resolved value.

Await.Error

Props

children · React.ReactNode | ((context: ErrorBoundaryContextType) => React.ReactNode) · required

The content to render when an error occurs. Can be a render function that receives error context.

asChild · boolean

When true, merges props into the child element instead of rendering a wrapper.

Await.Pending

Props

children · React.ReactNode · required

The content to display while the promise is pending.

Hook

useAwaitContext

function useAwaitContext<TValue>(): AwaitContextType<TValue>

Access the await context within child components.

Returns:

promise · Promise<TValue>

The original promise passed to Await.Root.

result · TValue

The resolved value of the promise.

Type Definitions

type AwaitContextType<TValue = unknown> = {
  promise: Promise<TValue>;
  result: TValue;
};

type ErrorFallbackProps = {
  error: unknown;
  resetErrorBoundary: (...args: unknown[]) => void;
};

Usage Examples

Basic Usage with Render Function

const userPromise = fetchUser();

<Await.Root promise={userPromise}>
  {(user) => <div>Welcome, {user.name}!</div>}
</Await.Root>

With Custom Fallbacks

<Await.Root
  promise={dataPromise}
  fallback={<LoadingSpinner />}
  errorFallback={({ error, resetErrorBoundary }) => (
    <div>
      <p>Error: {error.message}</p>
      <button onClick={resetErrorBoundary}>Retry</button>
    </div>
  )}
>
  {(data) => <DataDisplay data={data} />}
</Await.Root>

Using Component Parts

<Await.Root promise={productPromise}>
  <Await.Pending>
    <Skeleton />
  </Await.Pending>

  <Await.Success>
    {(product) => (
      <div>
        <h1>{product.name}</h1>
        <p>{product.description}</p>
      </div>
    )}
  </Await.Success>

  <Await.Error>
    {({ error, resetErrorBoundary }) => (
      <ErrorDisplay error={error} onRetry={resetErrorBoundary} />
    )}
  </Await.Error>
</Await.Root>

Without Suspense or Error Boundary

<Await.Root
  promise={configPromise}
  withSuspense={false}
  withErrorBoundary={false}
>
  {(config) => <ConfigPanel config={config} />}
</Await.Root>

Using asChild

<Await.Root promise={userPromise} asChild>
  <UserCard />
</Await.Root>