ProgressMeter

Examples #

'use client';

import { ProgressMeter } from '@coreux/ui';

export default function Default() {
  const value = 0.72;
  return (
    <div style={{ width: 280, boxSizing: 'border-box', background: '#F4F1E9', color: '#0B1221', padding: 24 }}>
      <p style={{ margin: '0 0 12px', fontSize: 14, lineHeight: 1.5 }}>Illustrative onboarding<br />72 of 100 steps complete</p>
      <div role="progressbar" aria-label="Illustrative onboarding completion" aria-valuemin={0} aria-valuemax={100} aria-valuenow={value * 100} aria-valuetext="72 of 100 steps complete">
        <div aria-hidden="true"><ProgressMeter value={value} /></div>
      </div>
    </div>
  );
}

Choosing a presentation #

Use ProgressMeter for a known fraction of a task or process completed. Always explain what the total represents. For a static headline metric use StatBlock; for a metric, supporting copy and meter on one surface use PanelCard’s progress slot. A meter does not compare categories or show change over time.

• Default · accent preserves the 0.72 seed and adds an illustrative onboarding label: 72 of 100 steps complete.
• Positive preserves the 0.92 positive seed, with an explicit “on track” status.
• On dark preserves the 0.45 seed, dark fieldMode and navy wrapper. The accent fill changes to cornflower.
• Neutral, muted, warning & error adds a complete data array of illustrative task snapshots. Text distinguishes paused, at-risk and blocked states.

All three seeds retain their component values, tones, field modes, 280 px wrappers and 24 px padding. The copied examples add visible labels and semantic wrappers. Every status and metric is illustrative; these are static snapshots, not a live upload or project tracker.

Inputs & settled state #

value is required: a finite number in the inclusive range 0–1. Use 0.72 for 72%, not 72. Zero and one are valid. Negative numbers, values above one, NaN and infinity throw. There is no indeterminate mode. Compute a fraction from a known, non-zero total before rendering.

fillProgress is a separate presentation input. It defaults to 1, so the entire value is visible. It must be finite and is clamped to 0–1, unlike value. It scales the existing fill from the left: value 0.72 and fillProgress 0.5 visually show half of the 72% fill. It does not change aria-valuenow, which remains the actual value. Keep the settled default for static documentation or status displays.

The component has no timer, easing, automatic transition or reduced-motion behavior. Consumers control any animation and should finish at 1 or skip the reveal for reduced motion. Changing fillProgress does not indicate new task completion. Unsupported fieldMode or tone values throw.

Geometry & appearance #

The track is 12 px tall and 100% of its parent’s content width. It includes a 1 px border and 1 px inner padding, with a pill radius and hidden overflow. The fill takes value × 100% of the inner content width. The seed wrappers are explicitly border-box: 280 px total width minus 48 px padding leaves a 232 px meter. Supply a bounded parent width; the component has no width, height, style or className prop.

fieldMode accepts light or dark and controls the track and border. The light track is pale steel with a slate border; dark uses a slate track and pale steel border. A matching outer surface belongs to the consumer wrapper.

tone accepts neutral, accent, muted, positive, warning and error, and changes the fill. Accent defaults to cobalt on light or cornflower on dark. Neutral uses navy or ivory; muted uses slate or pale steel; semantic fills use positive green, saffron and coral. These tones express presentation intent, not automatic thresholds. Select a status intentionally and write it in text; do not infer success from a percentage alone.

Some fill/track combinations, including positive green on pale steel and cornflower on the dark slate track, have less than 3:1 contrast. The examples include readable numeric values and status words so the bar is supplemental. If the graphic alone must communicate an exact state, choose a verified higher-contrast presentation or another component; there is no custom fill-color prop.

Props #

Types and required flags are extracted from the installed public declarations. Authored defaults are verified against the implementation.

Accessibility & layout #

The library renders role="progressbar" with aria-valuemin=0, aria-valuemax=1 and aria-valuenow=value. It does not supply an accessible name, accept label/ARIA props, or forward arbitrary DOM props. A named surrounding group alone does not name that inner progressbar.

Each complete example hides the library visual with an aria-hidden wrapper and provides a separate named outer progressbar with the equivalent 0–100 value and a descriptive aria-valuetext. This exposes one named progress indicator, while visible text supplies the task, amount and any status. Keep both values synchronized when adapting the example. Do not put interactive content inside the progressbar role; its descendants are presentational to assistive technology.

These wrappers describe determinate task completion. For a static measurement unrelated to progress, use suitable measurement semantics or a text summary instead. The component is not a live region; announce meaningful asynchronous updates separately when needed, without announcing every animation frame.

The meter follows its parent width, while these complete example wrappers use deliberate fixed widths. Fit to canvas scales the whole preview, including text; actual size preserves the copied layout in a focusable scroll region. In a responsive application you can give the meter a flexible bounded parent without changing its fixed 12 px height. Keep the label and value readable at narrow widths.

Consumer setup #

Browsing, previews, and copying are public. Installing the private @coreux/ui package requires repository read access and permission to use the bundled CoreUX brand fonts.

Follow the one-time installation guide for the pinned Git dependency, Tailwind v4 stylesheet setup, fonts, and troubleshooting. Keep the 'use client' directive in each example; no provider is required.

The quick start walks through a copied StatBlock in a minimal app.

Source & revision #

This reference targets @coreux/ui version 0.1.0 at 06f42fd. Types come from its installed declarations; explanations and defaults are checked against this implementation.

Revision and upgrade notes · Contribution and coverage guide