Loading Gate

Holds a region while it loads: nothing for a quick answer, a spinner after a moment, a note when it runs long, an error with a retry.

Pick how the server answers.

'use client';

import { useRef, useState } from 'react';
import { Button, LoadingGate } from '@brand-studio/ui';

const orders = ['Ethiopia Guji · 2 bags', 'Huila Washed · 1 bag', 'House Espresso · 3 bags'];

// The slow note and the time-out come sooner than the defaults (8 s and 20 s), so every stage shows in a short visit.
export default function LoadingGateDemo() {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string>();
  const [loaded, setLoaded] = useState(false);
  const timer = useRef(0);
  const load = (ms?: number) => {
    clearTimeout(timer.current);
    setError(undefined);
    setLoading(true);
    if (ms) timer.current = window.setTimeout(() => { setLoading(false); setLoaded(true); }, ms);
  };
  return (
    <div style={{ display: 'grid', gap: 16, width: '100%', maxWidth: 420 }}>
      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
        <Button tone="secondary" onClick={() => load(200)}>Quick answer</Button>
        <Button tone="secondary" onClick={() => load(4000)}>Slow answer</Button>
        <Button tone="secondary" onClick={() => load()}>No answer</Button>
      </div>
      <LoadingGate
        loading={loading}
        error={error}
        label="Loading orders"
        slowAfter={2500}
        timeout={6000}
        onTimeout={() => { setLoading(false); setError('Orders did not load'); }}
        onRetry={() => load(1200)}
        onCancel={() => { clearTimeout(timer.current); setLoading(false); }}
      >
        {loaded
          ? <ul style={{ margin: 0, paddingInlineStart: 20 }}>{orders.map(order => <li key={order}>{order}</li>)}</ul>
          : <p style={{ margin: 0 }}>Pick how the server answers.</p>}
      </LoadingGate>
    </div>
  );
}

Installation

pnpm add @brand-studio/ui

Usage

import { LoadingGate } from '@brand-studio/ui';
<LoadingGate
  loading={isLoading}
  error={failed ? 'Orders did not load' : undefined}
  label="Loading orders"
  onTimeout={abortRequest}
  onRetry={reload}
  onCancel={abortRequest}
>
  <OrderList orders={orders} />
</LoadingGate>

The gate follows the usual timing for waits. An answer within delay (400 ms) shows no indicator at all, because a flash is worse than a short pause. Once the spinner appears it stays for at least minDuration (600 ms). After slowAfter (8 s) a note says the wait is longer than usual and offers Cancel when you pass onCancel. After timeout (20 s) it calls onTimeout, so your app can stop the request and pass error. The demo shortens the last two so you can see each stage.

Pass a Skeleton as fallback when the content has a known shape. The skeleton then replaces the spinner, and the slow note still appears above it.

For a pressed button, use useDelayedLoading(saving) to decide when to show Button's loading state. It returns true from delay after the wait starts, then for at least minDuration.

Accessibility

  • A status line announces label when the spinner appears, then the slow note. It sits outside the busy region, so screen readers do not hold the announcements back.
  • The content region carries aria-busy while it waits. The error uses Alert in its critical tone, so screen readers hear it at once.
  • When Retry or Cancel disappears with its state, focus moves to the region instead of dropping to the page.

API Reference

PropTypeDefault
loadingboolean–
error?React.ReactNode–
onRetry?(() => void)–
onCancel?(() => void)–
onTimeout?(() => void)–
fallback?React.ReactNode–
children?React.ReactNode–
label?string'Loading'
delay?number400
minDuration?number600
slowAfter?number8000
timeout?number20000
slowMessage?React.ReactNode'This is taking longer than usual.'
errorHint?React.ReactNode'Check your connection, then try again.'
retryLabel?string'Try again'
cancelLabel?string'Cancel'
className?string''

Still, Deskhand and Hollis are fictional brands. The coffee photographs are original generated artwork. @brand-studio/ui is MIT licensed.