Progress

Connect the behavior

Tie feedback to the operation it describes. Distinguish waiting, success, failure and an empty result instead of reusing one message for every state. Keep essential recovery instructions available in the page even if a temporary notification disappears.

Copy the composition, then connect its intent. Replace sample records and callbacks with your own data flow. For options such as value, defaultValue, open or onChange, use only those documented in this component's API; different components expose different contracts.

Give each piece of state one owner. Keep a temporary selection inside the interface when nothing else needs it; lift shared values into a parent when other controls depend on them. Read the prop reference before combining controlled values with defaults. A default normally initializes a control; it is not a substitute for updating its current value.

Connect requests in an event handler or your application’s data layer, never as a side effect of rendering. Keep pending, completed and failed outcomes distinct, preserve useful input after an error, and offer a clear recovery action. If the integration subscribes to an external source, remove that subscription when its owner unmounts; cancel or ignore obsolete requests so an earlier response cannot replace newer results.

Report work that actually happened. Feed completed from your task and supply a positive total when it becomes known. Until then, value={null} communicates an unknown duration. This wrapper derives the visible label and accessible value from the same numbers; it does not start a timer or pretend that an upload has finished.

import { Progress } from "@kamod-ch/ui";

type TaskProgressProps = { completed: number; total: number | null };

export function TaskProgress({ completed, total }: TaskProgressProps) {
  const knownTotal = total !== null && Number.isFinite(total) && total > 0;
  const current = knownTotal ? Math.min(total, Math.max(0, completed)) : 0;
  const label = knownTotal ? `${current} of ${total} items` : "Preparing items…";

  return (
    <div class="grid gap-2">
      <p>{label}</p>
      <Progress
        value={knownTotal ? current : null}
        max={knownTotal ? total : 100}
        aria-label="Processing items"
        aria-valuetext={label}
      />
    </div>
  );
}

Reaching the maximum means the measured steps finished, not necessarily that the server accepted the result. Keep final processing and failure messages separate from the bar, and remove the loading state when the operation settles. Avoid making every percentage update a live announcement; announce meaningful milestones instead.

Start with the live preview, then exercise the same interaction with your actual data. The type definitions describe accepted values; they do not implement persistence, navigation or server-side validation for you. Keep those responsibilities in the application that composes the UI.

Refine the presentation

Let a parent own the surrounding spacing. Keep related elements together with gap and use semantic surface/foreground pairs so the composition follows the active theme. The wrapper below changes the surrounding layout without assuming extra props on Progress.

Put the chosen example inside ExampleSurface, then refine supported variants and sizes using the API above. For application-wide changes, adjust theme tokens instead of repeating fixed colors. See Component styles for hierarchy, density and focus treatments.

Review the complete interaction

• Confirm that status is understandable without color, animation or an icon alone.
• Exercise both completion and failure paths; stop loading indicators when the operation finishes.
• Use announcements only when needed and avoid repeatedly announcing unchanged background activity.

The preview's narrow control changes its container width. Also resize the browser when checking viewport-based Tailwind utilities such as sm: and md:, and test overlays in the full page where their portals render.