Progress

Code

import { Progress } from "@fadymondy/nasaq/web";export function Upload({ percent }: { percent: number }) {  return <Progress value={percent} label="Uploading files" />;}

Loading & States · stable

Live examples and controls: Progress in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/progress.json

Two thin bars that look alike and mean different things. Progress shows a task moving toward done: an upload, an import, a setup. Meter shows an amount against a limit: seats used, storage, a monthly budget. The fill starts at the inline start, so it grows from the right in Arabic.

When to useCopy Anchor Link

• Progress: something with a start and an end that takes long enough to see. Pass value={null} when the length is unknown.
• Meter: a quota or budget where crossing a threshold matters. It changes tone for you.

When not to useCopy Anchor Link

• A short wait with no length: use Spinner or a LoadingState.
• A rating or score: use Rating.
• A single status word: use Status or Badge.
• A written warning about a limit: pair a Meter with an Alert.

ImportCopy Anchor Link

import { Meter, Progress } from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"

Quick startCopy Anchor Link

import { Progress } from "@fadymondy/nasaq/web";

export function Upload({ percent }: { percent: number }) {
  return <Progress value={percent} label="Uploading files" />;
}

AnatomyCopy Anchor Link

Progress / Meter          Base UI Root (role="progressbar" / role="meter")   data-slot="progress" | "meter"
├─ head                   label + value row (when label or showValue)        data-slot="progress-head"
└─ track                                                                     data-slot="progress-track" | "meter-track"
   └─ indicator           the fill                                           data-slot="progress-indicator" | "meter-indicator"

Both roots carry data-tone with the tone in use.

APICopy Anchor Link

ProgressCopy Anchor Link

ProgressProps extends ComponentProps<"div"> (without children).

MeterCopy Anchor Link

MeterProps shares the props above (label, showValue, valueText, format, locale, size, min, max) and has:

ExamplesCopy Anchor Link

Unknown length, then determinateCopy Anchor Link

import { Progress } from "@fadymondy/nasaq/web";

export function Import({ percent }: { percent: number | null }) {
  return (
    <Progress
      value={percent}
      tone={percent === 100 ? "success" : "default"}
      label={percent === null ? "Preparing…" : "Importing"}
    />
  );
}

Quota with visible textCopy Anchor Link

import { Meter } from "@fadymondy/nasaq/web";

export function Seats() {
  return <Meter value={42} max={50} label="Seats" valueText="42 of 50" />;
}

Budget in Arabic, custom thresholdsCopy Anchor Link

import { Meter } from "@fadymondy/nasaq/web";

export function BudgetAr() {
  return (
    <Meter
      value={7200}
      max={10000}
      warnAt={0.7}
      dangerAt={0.9}
      locale="ar-SA"
      format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }}
      label="ميزانية الذكاء الاصطناعي"
    />
  );
}

AccessibilityCopy Anchor Link

• Progress is role="progressbar" with aria-valuenow, aria-valuemin, aria-valuemax (no aria-valuenow when indeterminate). Meter is role="meter".
• The label names the bar. If you omit label, pass aria-label or aria-labelledby.
• Colour is never the only carrier: the value text stays visible, and a threshold crossing should be backed by text (an Alert or valueText).
• Nothing is focusable and no keys apply.
• Indeterminate uses a pulse that stops under prefers-reduced-motion; width changes do not animate then either.

RTL & i18nCopy Anchor Link

• The fill is positioned with inset-inline-start, so it grows from the right in RTL. The head row (label, value) mirrors with the document.
• Numbers format with locale (pass "ar-SA" for Arabic-Indic digits). The component has no built-in strings; localise label and valueText.

Styling & tokensCopy Anchor Link

• Track bg-nq-surface-soft, fill bg-primary (default) or bg-nq-info / -success / -warning / -danger; rounded-full; 300ms width transition on ease-nq.
• Target [data-slot=progress], [data-slot=meter], [data-tone=warning], progress-track, progress-indicator. Extend with className; set the width with a wrapper or className (the bar is w-full).

Do / Don'tCopy Anchor Link

• Do use Meter for limits and Progress for tasks; the semantics differ for assistive tech.
• Do show the numbers ("42 of 50"), not just the bar.
• Don't use danger on a Progress unless the task failed; stop the bar and show an Alert.
• Don't fake a percentage for unknown work: use value={null}.

RelatedCopy Anchor Link

• Spinner · States · Alert · Status

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-loading-states-progress--docs