# 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.

```tsx
'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

```sh
npm install @brand-studio/ui
```

React 18 or 19 is a peer dependency. Import the stylesheet once and wrap the app in a brand theme:

```tsx
import '@brand-studio/ui/styles.css';
import { BrandTheme, LoadingGate } from '@brand-studio/ui';
import brand from './brand.json';

<BrandTheme palette={brand.tokens} mode="system">
  {/* your app */}
</BrandTheme>
```

## Usage

```tsx
import { LoadingGate } from '@brand-studio/ui';
```

```tsx
<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

| Prop | Type | Default |
|---|---|---|
| `loading` | `boolean` | – |
| `error?` | `React.ReactNode` | – |
| `onRetry?` | `(() => void)` | – |
| `onCancel?` | `(() => void)` | – |
| `onTimeout?` | `(() => void)` | – |
| `fallback?` | `React.ReactNode` | – |
| `children?` | `React.ReactNode` | – |
| `label?` | `string` | `'Loading'` |
| `delay?` | `number` | `400` |
| `minDuration?` | `number` | `600` |
| `slowAfter?` | `number` | `8000` |
| `timeout?` | `number` | `20000` |
| `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` | `''` |

Source: https://brandstudio.js.org/docs/components/loading-gate/
