ProgressBar

کامپوننت ProgressBar برای نمایش میزان پیشرفت یک عملیات استفاده می‌شود؛ مثل آپلود فایل یا تکمیل یک فرم چندمرحله‌ای.

Import

import { ProgressBar } from "fara-ui";

اگر هنوز FaraUI را نصب و راه‌اندازی نکرده‌ای، ابتدا صفحه‌ی شروع به کار را ببین.

Basic Usage

<ProgressBar value={60} />

Playground

آپلود فایل40%

value

variant

label

showValue

indeterminate

<ProgressBar
  value={40}
  variant="primary"
  label="آپلود فایل"
  showValue
/>

Variant

primary (پیش‌فرض) — رنگ اصلی برند
success — تکمیل موفق
danger — خطا یا وضعیت بحرانی

Indeterminate

اگر میزان پیشرفت مشخص نیست (مثلاً منتظر پاسخ سرور)، با indeterminate یک انیمیشن بی‌پایان نمایش داده می‌شود و value نادیده گرفته می‌شود. درصد نمایشی هم در این حالت مخفی است.

<ProgressBar indeterminate label="در حال دریافت اطلاعات..." aria-label="در حال دریافت اطلاعات" />

Value

value عددی بین ۰ تا ۱۰۰ است و به‌صورت خودکار clamp می‌شود؛ لازم نیست خودت از حد نگذرانی. با label و showValue یک ردیف برچسب بالای نوار رندر می‌شود که درصد فعلی را هم نشان می‌دهد.

Accessibility

کامپوننت با role="progressbar" و aria-valuenow/aria-valuemin/aria-valuemax پیاده شده، پس screen reader ها میزان پیشرفت را اعلام می‌کنند.
این role روی track داخلی قرار دارد؛ برای حالت indeterminate که aria-valuenow ندارد، یک aria-label توصیفی روی خود ProgressBar قرار بده.
label به‌صورت خودکار به attributeهای ARIA متصل نمی‌شود؛ اگر متن برای دسترسی مهم است، از aria-label یا aria-describedby استفاده کن.

Data Attributes and Customize CSS

ProgressBar hookهای زیر را تولید می‌کند:

Attribute	کاربرد
`data-fara-progress-bar`	root کامپوننت
`data-fara-progress-label-row`	ردیف label و درصد
`data-fara-progress-track`	مسیر با `role="progressbar"`
`data-fara-progress-fill`	بخش پرشده یا انیمیشن indeterminate
`data-variant`	variant روی fill: `primary`، `success` یا `danger`
`data-indeterminate`	روی fill در حالت indeterminate

<ProgressBar className="upload-progress" value={72} variant="success" label="آپلود" showValue />

[data-fara-progress-bar] {
  width: min(480px, 100%);
}

[data-fara-progress-fill][data-variant="success"] {
  background: #16a34a;
}

[data-fara-progress-fill][data-indeterminate] {
  background: linear-gradient(90deg, transparent, #2563eb, transparent);
}

className روی root قرار می‌گیرد. برای استایل مسیر یا fill از data-fara-progress-track و data-fara-progress-fill استفاده کن.

Props

Prop	Type	Default	Description
`value`	`number`	`0`	درصد پیشرفت (۰ تا ۱۰۰)
`variant`	`"primary" \| "success" \| "danger"`	`"primary"`	رنگ نوار
`label`	`string`	-	برچسب بالای نوار
`showValue`	`boolean`	`false`	نمایش درصد کنار برچسب
`indeterminate`	`boolean`	`false`	حالت بدون درصد مشخص
`className`	`string`	-	کلاس CSS اضافی برای سفارشی‌سازی
`ref`	`Ref<HTMLDivElement>`	-	دسترسی مستقیم به المان DOM

علاوه بر موارد بالا، تمام ویژگی‌های استاندارد <div> نیز پشتیبانی می‌شوند.

Import​

Basic Usage​

Playground​

Variant​

Indeterminate​

Value​

Accessibility​

Data Attributes and Customize CSS​

Props​