ProvisioningStatus

Provisioning, waking, and error panel states with a live detail line.

ProvisioningStatus narrates the wait between “create app” and a running sandbox. One quiet stage, three acts: while provisioning or waking, the NeonLoader resolves out of grain above a headline and a shimmering mono detail line — feed detail from your API and each step crossfades in place. On error, the loader yields to the house error treatment (mono tag, foreground sentence) with a retry action. The frame and rhythm never change between states.

Provisioning your app

Creating Neon project…

"use client";

import { useEffect, useState } from "react";

import { provisioningSteps, sampleErrorDetail } from "./fixtures";
import type { ProvisioningState } from "./provisioning-status";
import { ProvisioningStatus } from "./provisioning-status";

const STATES: ProvisioningState[] = ["provisioning", "waking", "error"];
const STEP_MS = 1800;

export const ProvisioningStatusDemo = () => {
  const [state, setState] = useState<ProvisioningState>("provisioning");
  const [step, setStep] = useState(0);

  useEffect(() => {
    if (state !== "provisioning") {
      return;
    }

    const timer = window.setInterval(
      () => setStep((current) => (current + 1) % provisioningSteps.length),
      STEP_MS
    );
    return () => window.clearInterval(timer);
  }, [state]);

  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <ProvisioningStatus
        detail={state === "error" ? sampleErrorDetail : undefined}
        onRetry={() => setState("provisioning")}
        state={state}
        {...(state === "provisioning" && { detail: provisioningSteps[step] })}
      />
      <div className="flex gap-1.5">
        {STATES.map((option) => (
          <button
            className={
              option === state
                ? "border border-primary/60 px-2.5 py-1 font-mono text-foreground text-xs"
                : "border border-border/60 px-2.5 py-1 font-mono text-muted-foreground text-xs transition-colors hover:border-border hover:text-foreground"
            }
            key={option}
            onClick={() => setState(option)}
            type="button"
          >
            {option}
          </button>
        ))}
      </div>
    </div>
  );
};

export default ProvisioningStatusDemo;

Install

npx shadcn@latest add https://ui.neon.com/r/provisioning-status.json

Usage

import { ProvisioningStatus } from "@/components/neon-ui/provisioning-status";

<ProvisioningStatus
  state={app.state}
  detail={app.provisioningStep}
  onRetry={() => provision(app.id)}
/>;

Wiring to Neon

Provisioning is a Neon operation, so poll the project’s operations and map their status onto the panel:

import { createNeonClient } from "@/lib/neon-client";

const neon = createNeonClient(process.env.NEON_API_KEY);
const { data } = await neon.operations.list(projectId).page();
const pending = data?.items.find(
  (operation) =>
    operation.status === "running" || operation.status === "scheduling"
);
// state: pending ? "provisioning" : failed ? "error" : done
// detail: pending?.action, e.g. "create_compute" mapped to your own copy

failed, error, and cancelled all mean the panel shows error; start_compute on an existing project is the waking case. Turn operation.action into your own sentence rather than showing the raw action name, and swap detail as each operation completes so the line crossfades instead of jumping.

States

Provisioning — loader + headline + shimmering detail. Swap detail as your API reports progress (“Creating Neon project…” → “Provisioning database…”) and it crossfades in place.
Waking — identical staging with wake copy; the sandbox exists, it’s just cold.
Error — mono error tag with a foreground sentence, muted detail, and a retry action where the shimmer was.

Props

PropType

state?"provisioning" | "waking" | "error"

Lifecycle state the panel narrates.

Type"provisioning" | "waking" | "error"

Default"provisioning"

title?string

Override the state's default headline.

Typestring

detail?string

Status detail line; swapping it crossfades in place.

Typestring

onRetry?() => void

Renders the retry action in the error state.

Type() => void

retryLabel?string

Label for the retry action.

Typestring

Default"Try again"

variant?"panel" | "bare"

panel draws the house surface; bare embeds in an already-bordered pane.

Type"panel" | "bare"

Default"panel"

size?"sm" | "md" | "lg"

Vertical breathing room.

Type"sm" | "md" | "lg"

Default"md"

footer?ReactNode

Extra content under the detail line, e.g. a cancel link.

TypeReactNode

Accessibility

The detail line is aria-live="polite", so step changes are announced without interrupting.
The error headline is role="alert"; the loader is decorative here (the visible text carries the status).
Shimmer and crossfades are static under prefers-reduced-motion.