Meters

# Brok UI: Circular Progress (`circular-progress`)

A static SVG ring progress indicator with a track, coloured arc, and optional centred percentage readout. Supports a `min` floor, an opt-in status tone and a custom inner value label. Shares its value/size vocabulary with gauge.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add circular-progress
```

## Usage

```blade
<div class="w-full flex flex-wrap items-center justify-center gap-8">
    <div class="flex flex-col items-center gap-2">
        <x-ui.circular-progress :value="25" :size="64" :thickness="6" />
        <span class="text-sm text-muted-foreground">25%</span>
    </div>
    <div class="flex flex-col items-center gap-2">
        <x-ui.circular-progress :value="72" :size="64" :thickness="6" />
        <span class="text-sm text-muted-foreground">72%</span>
    </div>
    <div class="flex flex-col items-center gap-2">
        <x-ui.circular-progress :value="100" :size="64" :thickness="6" />
        <span class="text-sm text-muted-foreground">100%</span>
    </div>
    <div class="flex flex-col items-center gap-2">
        <x-ui.circular-progress indeterminate :size="64" :thickness="6" :show-value="false" />
        <span class="text-sm text-muted-foreground">Loading…</span>
    </div>
</div>
```

## Props

- `value` (int, default `0`) — Current value, clamped between min and max.
- `min` (int, default `0`) — Floor of the value range.
- `max` (int, default `100`) — Ceiling of the value range.
- `size` (int, default `44`) — Outer diameter in pixels.
- `thickness` (mixed|null, default `null`) — Stroke width in pixels; the canonical name, shared with gauge.
- `stroke` (mixed|null, default `null`) — Legacy alias for thickness, kept for backward compatibility; thickness wins when both are set.
- `showValue` (bool, default `true`) — Shows the centred percentage readout.
- `indeterminate` (bool, default `false`) — Renders a fixed partial arc that spins continuously, for an unknown-duration loading state.
- `label` (mixed|null, default `null`) — Accessible name for the progressbar; required by WCAG when the consumer has not set aria-label or aria-labelledby.
- `tone` (mixed|null, default `null`) — Opt-in status colour for the arc (positive, attention, negative, neutral) instead of the default brand colour; colours what the value means, not how much of it there is.
- `valueLabel` (mixed|null, default `null`) — Replaces the numeric percent readout entirely, such as with a status word.
- `suffix` (string, default `%`) — Text appended to the percent readout when valueLabel is not set.

## Use when

- Use when trend, distribution, flow, intensity, or relationship questions are easier to answer visually than in raw numbers.
- Showing a single value as a percentage-of-completion ring, such as a task, upload or onboarding progress indicator.
- Needing a compact, static loading spinner via indeterminate.

## Avoid when

- Do not use a chart when users mainly need exact lookup or when a single metric would be clearer as text or a stat.
- The value is a fill level meant to read as a dial with min/max ticks; use gauge instead.
- Several values must compare on one axis; use chart instead.

## Anti-patterns

- Decorative charts without a meaningful question

## Rules

- Use the `<brok:circular-progress>` tag (or `<x-ui.circular-progress>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/circular-progress
- Registry JSON (files, props, contract): https://brokui.dev/r/open/circular-progress.json

@props([
    'value'         => 0,
    'min'           => 0,
    'max'           => 100,
    'size'          => 44,
    // Canonical name, shared with the gauge component. `stroke` (below) is a
    // deprecated alias kept for backward compatibility.
    'thickness'     => null,
    'stroke'        => null,
    'showValue'     => true,
    'indeterminate' => false,
    // Accessible name — role="progressbar" requires one (WCAG). Skipped when the
    // consumer supplies aria-label/aria-labelledby themselves.
    'label'         => null,
    // Opt-in: colours the arc by what the value MEANS rather than how much of
    // it there is — a record 40% complete is not "40%", it is not ready. Left
    // null (default), the arc keeps today's `text-primary` colouring.
    // positive | attention | negative | neutral
    'tone'          => null,
    // Opt-in inner readout override. `valueLabel` replaces the numeric percent
    // entirely (e.g. a status word) when set; `suffix` only changes what is
    // appended to the percent (defaults to '%', so plain usage is unaffected).
    'valueLabel'    => null,
    'suffix'        => '%',
])

@php
    $needsName = $label === null && ! $attributes->has('aria-label') && ! $attributes->has('aria-labelledby');
    $sizePx  = (int) $size;
    // `thickness` wins when both are given; `stroke` keeps old markup working.
    $strokeW = (int) ($thickness ?? $stroke ?? 4);
    $cx      = $sizePx / 2;
    $cy      = $sizePx / 2;
    $r       = ($sizePx - $strokeW) / 2;

    $circumference = 2 * M_PI * $r;
    $min = (float) $min;
    $max = (float) $max;

    if ($indeterminate) {
        // Fixed 25 % partial arc for the indeterminate spinner.
        $dashOffset = $circumference * 0.75;
    } else {
        $value      = max($min, min((float) $value, $max));
        $span       = ($max - $min) != 0 ? ($max - $min) : 1;
        $fraction   = ($value - $min) / $span;
        $dashOffset = $circumference * (1 - $fraction);
        $percent    = (int) round($fraction * 100);
    }

    // Tone is independent of the value: a caller opts in with one of these four
    // words, or leaves it unset and gets the original brand-coloured arc. Same
    // `-text` status tokens `stat` uses for its tone map, so a ring and a KPI
    // tile in the same screen agree on what "positive"/"negative" look like.
    // The readout must sit inside the ring, so its size follows the INNER
    // diameter (outer size minus both stroke widths) and the label length —
    // "100%" at size 64 / stroke 6 has 52px to live in, not 64. The width
    // estimate uses ~0.6em per tabular digit and fills at most 72% of the
    // inner diameter so the digits sit clear of the arc; the height cap keeps
    // short labels from ballooning.
    $inner = max(8, $sizePx - 2 * $strokeW);
    $readout = $indeterminate ? '' : ($valueLabel ?? ($percent.$suffix));
    $chars = max(1, mb_strlen($readout));
    $valueFontSize = (int) floor(min($inner * 0.34, ($inner * 0.72) / ($chars * 0.6)));
    $valueFontSize = max(9, $valueFontSize);

    $validTones = ['positive', 'attention', 'negative', 'neutral'];
    $toneClass = in_array($tone, $validTones, true) ? match ($tone) {
        'positive' => 'text-success-text',
        'attention' => 'text-warning-text',
        'negative' => 'text-destructive-text',
        default => 'text-muted-foreground', // neutral
    } : null;
@endphp

<div
    data-slot="circular-progress"
    @if ($toneClass !== null) data-tone="{{ $tone }}" @endif
    role="progressbar"
    aria-valuemin="{{ $min }}"
    aria-valuemax="{{ $max }}"
    @if ($label !== null) aria-label="{{ $label }}" @elseif ($needsName) aria-label="{{ __('Progress') }}" @endif
    @unless ($indeterminate) aria-valuenow="{{ $value }}" @endunless
    {{ $attributes->merge(['class' => 'relative inline-flex items-center justify-center']) }}
    style="width: {{ $sizePx }}px; height: {{ $sizePx }}px;"
>
    <svg
        width="{{ $sizePx }}"
        height="{{ $sizePx }}"
        viewBox="0 0 {{ $sizePx }} {{ $sizePx }}"
        fill="none"
        aria-hidden="true"
        @class(['motion-safe:animate-spin' => $indeterminate])
    >
        {{-- Track --}}
        <circle
            class="text-muted"
            cx="{{ $cx }}"
            cy="{{ $cy }}"
            r="{{ $r }}"
            stroke="currentColor"
            stroke-width="{{ $strokeW }}"
        />
        {{-- Arc --}}
        <circle
            class="{{ $toneClass ?? 'text-primary' }} transition-[stroke-dashoffset] duration-500 ease-out motion-reduce:transition-none"
            cx="{{ $cx }}"
            cy="{{ $cy }}"
            r="{{ $r }}"
            stroke="currentColor"
            stroke-width="{{ $strokeW }}"
            stroke-linecap="round"
            transform="rotate(-90 {{ $cx }} {{ $cy }})"
            stroke-dasharray="{{ $circumference }}"
            stroke-dashoffset="{{ $dashOffset }}"
        />
    </svg>

    @if ($showValue && !$indeterminate)
        {{-- `text-foreground` on purpose, even when `tone` is set: the arc
             already carries the tone, and colouring the number too makes a
             negative row shout twice. --}}
        <span
            data-slot="circular-progress-value"
            @class([
                'absolute text-foreground tabular-nums',
                'max-w-full truncate px-1 text-center' => $valueLabel !== null,
            ])
            style="font-size: {{ $valueFontSize }}px; line-height: 1;"
            aria-hidden="true"
        >{{ $readout }}</span>
    @endif
</div>