Feedback

Progress Display

Composite progress affordance with label, percentage, and bar.

Preview

'use client';

import { ProgressDisplay } from '@brika/clay/components/progress-display';
import { useRef } from 'react';

/** In-progress state, spinner, phase label, and a live log stream. */
export default function ProgressDisplayDefaultDemo() {
  const scrollRef = useRef<HTMLDivElement | null>(null);
  return (
    <div className="w-full max-w-md">
      <ProgressDisplay
        progressValue={48}
        phaseLabel="Deploying to production…"
        logs={[
          'Building Docker image',
          'Pushing to registry (sha256:a3f7…)',
          'Starting container on us-east-1a',
          'Health check: waiting for /healthz',
        ]}
        scrollRef={scrollRef}
        error={null}
        success={false}
        isProcessing
      />
    </div>
  );
}

01 Installation

Install

Pull Progress Display from the barrel for everyday use, or the granular path when you want a tighter bundle.

tsxBarrel1 line

import { ProgressDisplay } from "@brika/clay";

tsxGranular1 line

import { ProgressDisplay } from "@brika/clay/components/progress-display";

02 Usage

A minimal example

Drop this into a page. Native HTML attributes pass through to the underlying primitive.

tsxProgress Display.tsx27 lines

'use client';

import { ProgressDisplay } from '@brika/clay/components/progress-display';
import { useRef } from 'react';

/** In-progress state, spinner, phase label, and a live log stream. */
export default function ProgressDisplayDefaultDemo() {
  const scrollRef = useRef<HTMLDivElement | null>(null);
  return (
    <div className="w-full max-w-md">
      <ProgressDisplay
        progressValue={48}
        phaseLabel="Deploying to production…"
        logs={[
          'Building Docker image',
          'Pushing to registry (sha256:a3f7…)',
          'Starting container on us-east-1a',
          'Health check: waiting for /healthz',
        ]}
        scrollRef={scrollRef}
        error={null}
        success={false}
        isProcessing
      />
    </div>
  );
}

03 Examples

Progress Display, every way

Error

Error state, bar turns destructive and the error message block appears.

GitHub

'use client';

import { ProgressDisplay } from '@brika/clay/components/progress-display';
import { useRef } from 'react';

/** Error state, bar turns destructive and the error message block appears. */
export default function ProgressDisplayErrorDemo() {
  const scrollRef = useRef<HTMLDivElement | null>(null);
  return (
    <div className="w-full max-w-md">
      <ProgressDisplay
        progressValue={35}
        phaseLabel="Deployment failed"
        logs={[
          'Building Docker image',
          'Pushing to registry',
          'Container failed to start',
        ]}
        scrollRef={scrollRef}
        error="Exit code 1: health check timed out after 30s. The container is not responding on port 8080."
        success={false}
        isProcessing={false}
      />
    </div>
  );
}

Success

Success state, bar turns green and an optional success message is shown.

GitHub

'use client';

import { ProgressDisplay } from '@brika/clay/components/progress-display';
import { useRef } from 'react';

/** Success state, bar turns green and an optional success message is shown. */
export default function ProgressDisplaySuccessDemo() {
  const scrollRef = useRef<HTMLDivElement | null>(null);
  return (
    <div className="w-full max-w-md">
      <ProgressDisplay
        progressValue={100}
        phaseLabel="Deployment complete"
        logs={[
          'Building Docker image',
          'Pushing to registry',
          'Container started',
          'Health check passed',
        ]}
        scrollRef={scrollRef}
        error={null}
        success
        isProcessing={false}
        successMessage="Deployed successfully to production. Traffic is being routed."
      />
    </div>
  );
}

04 Accessibility

Accessibility

Log entries update via a live region, AT announces new lines as they stream in.
Error and success states should also be communicated via a toast or alert for AT users in background contexts.
The scrollable log area should be reachable by keyboard when it overflows.

05 Tokens 11 theme-overridable

Theme tokens

Every CSS variable Progress Display reads, with its default and the dotted path you'd write in a ThemeConfig JSON to override it. Set any of these in your theme to retune Progress Display without touching component code.

Progress Display tokens

11 tokens

ColorFill, border, and text colors.10

--progress-display-phase-foregroundcolorvar(--muted-foreground)
components.progressDisplay.phaseForeground
Text color of the phase label rendered above the bar.
--progress-display-log-foregroundcolorvar(--muted-foreground)
components.progressDisplay.logForeground
Text color of the log entries (and empty-logs message) inside the scroll area.
--progress-display-log-bgcolorcolor-mix(in oklch, var(--muted) 30%, transparent)
components.progressDisplay.logBg
Background fill of the log scroll area surface.
--progress-display-spinner-colorcolorvar(--primary)
components.progressDisplay.spinnerColor
Color of the in-flight spinner glyph shown while processing.
--progress-display-success-colorcolorvar(--success)
components.progressDisplay.successColor
Color of the success indicator (check icon and progress fill) and the success block accents.
--progress-display-success-bgcolorcolor-mix(in oklch, var(--success) 10%, transparent)
components.progressDisplay.successBg
Background fill of the success message block.
--progress-display-success-bordercolorcolor-mix(in oklch, var(--success) 50%, transparent)
components.progressDisplay.successBorder
Border color of the success message block.
--progress-display-error-colorcolorvar(--destructive)
components.progressDisplay.errorColor
Color of the error indicator (X icon and progress fill) and the error block text.
--progress-display-error-bgcolorcolor-mix(in oklch, var(--destructive) 10%, transparent)
components.progressDisplay.errorBg
Background fill of the error message block.
--progress-display-error-bordercolorcolor-mix(in oklch, var(--destructive) 50%, transparent)
components.progressDisplay.errorBorder
Border color of the error message block.

ElevationDrop shadow and depth.1

--progress-display-backdrop-blurblur0px
components.progressDisplay.backdropBlur
Backdrop blur applied to the progress-display log surface. Set non-zero for a frosted-glass treatment.

Override in a theme

Authoring a theme is plain JSON. Drop overrides under components.progressDisplay, the names are camelCase versions of the variable suffix.

jsonmy-theme.json12 lines

{
  "id": "my-theme",
  "name": "My Theme",
  "description": "...",
  "accentSwatches": ["#000"],

  "components": {
    "progressDisplay": {
      "phaseForeground": "var(--muted-foreground)"
    }
  }
}

Then apply with applyTheme(myTheme) (see the theming guide), scope it to a subtree with themeToCssVars(myTheme, mode), or consume any token directly in your own JSX with the matching Tailwind utility (e.g. bg-progress-display-…) — see the chips on each token row.

06 API reference

API reference

Props specific to Progress Display. Native HTML attributes pass through to the underlying primitive, see the component source on GitHub for the full type signature.

error*
string | null
Error message; when set, the bar turns destructive and an error block is shown.
isProcessing*
boolean
Whether work is in flight; controls the spinner and empty-state copy.
logs*
string[]
Lines rendered in the log scroll area, oldest first.
phaseLabel*
string
Short label rendered above the bar (e.g. "Uploading…").
progressValue*
number
Progress percentage from 0 to 100. Drives the bar fill width.
scrollRef*
RefObject<HTMLDivElement | null>
Ref attached to the inner log container so callers can auto-scroll.
success*
boolean
Marks the run as finished successfully; turns the bar green and shows a check.
emptyLogsMessage
string
Copy shown when logs is empty and isProcessing is true.
successMessage
string
Copy shown in the success block when success is true.