Rating

کامپوننت Rating برای امتیازدهی کاربر با ستاره استفاده می‌شود؛ مثل امتیاز دادن به یک محصول یا محتوا. با قرار گرفتن ماوس روی ستاره‌ها پیش‌نمایش امتیاز به‌صورت زنده نمایش داده می‌شود.

Import

import { Rating } from "fara-ui";

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

Basic Usage

import { useState } from "react";
import { Rating } from "fara-ui";

export function ProductRating() {
  const [score, setScore] = useState(3);

  return (
    <div>
      <Rating value={score} onChange={setScore} />
      <p>امتیاز شما: {score} از ۵</p>
    </div>
  );
}

برای نمایش امتیاز بدون اجازه‌ی تغییر، فقط value و readOnly را بده:

<Rating value={4} readOnly />

Playground

value

max

readOnly

<Rating value={3} max={5} onChange={...} />

Read Only

با readOnly ستاره‌ها غیرقابل کلیک می‌شوند و فقط برای نمایش امتیاز موجود استفاده می‌شوند؛ مثلاً نمایش میانگین امتیاز یک محصول در لیست محصولات.

Number of Stars

با max می‌توانی تعداد ستاره‌ها را تغییر بدهی (پیش‌فرض ۵).

<Rating value={8} max={10} onChange={(value) => console.log("score:", value)} />

value باید عددی بین صفر و max باشد. onChange فقط وقتی کاربر روی یک ستاره کلیک کند اجرا می‌شود.

Accessibility

• کامپوننت با role="radiogroup" و هر ستاره با role="radio" پیاده شده، پس با صفحه‌کلید (Tab, Enter) قابل استفاده است.
• هر ستاره یک aria-label توصیفی مثل «۳ از ۵ ستاره» دارد.
• در حالت فقط‌خواندنی، دکمه‌های ستاره غیرفعال می‌شوند.
• چون کامپوننت خودش aria-label="امتیاز" دارد، برای استفاده در فرم‌های مختلف بهتر است context یا label اطراف آن را هم مشخص کنی.

Data Attributes and Customize CSS

Rating دو hook پایدار دارد:

<div data-fara-rating>
  <button data-fara-rating-star data-filled="true"></button>
</div>

Attribute	کاربرد
data-fara-rating	ریشه‌ی گروه امتیاز
data-fara-rating-star	هر ستاره
data-filled	پر بودن ستاره بر اساس مقدار فعلی یا hover

برای یک نمونه‌ی خاص از className استفاده کن:

<Rating className="review-rating" value={score} onChange={setScore} />

.review-rating {
  gap: 6px;
}

[data-fara-rating-star][data-filled] {
  color: #f59e0b;
}

[data-fara-rating] {
  direction: ltr;
}

Rating از نظر جهت تعامل به‌صورت LTR طراحی شده است؛ برای صفحه‌ی RTL همین جهت را حفظ کن تا ترتیب ستاره‌ها و مقداردهی قابل پیش‌بینی بماند.

Props

Prop	Type	Default	Description
value	number	-	امتیاز فعلی (الزامی)
onChange	(value: number) => void	-	هنگام کلیک روی ستاره صدا زده می‌شود
max	number	5	تعداد ستاره‌ها
readOnly	boolean	false	غیرفعال کردن تعامل کاربر
className	string	-	کلاس CSS اضافی برای سفارشی‌سازی