Radio

کامپوننت Radio برای انتخاب یک گزینه از میان چند گزینه‌ی مرتبط استفاده می‌شود؛ مثل انتخاب یک طرح اشتراک یا یک روش ارسال. برای گروهی از گزینه‌ها معمولاً از RadioGroup استفاده می‌کنی که مدیریت state را ساده‌تر می‌کند.

Import

import { Radio, RadioGroup } from "fara-ui";

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

Basic Usage

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

export function PlanSelector() {
  const [plan, setPlan] = useState("free");

  return (
    <div>
      <RadioGroup
        name="plan"
        options={[
          { value: "free", label: "رایگان" },
          { value: "pro", label: "حرفه‌ای" },
        ]}
        value={plan}
        onChange={setPlan}
      />
      <p>طرح انتخاب‌شده: {plan}</p>
    </div>
  );
}

Playground

رایگانحرفه‌ایسازمانی

valuefreeproenterprise

disabled

<RadioGroup
  name="plan"
  options={[...]}
  value="pro"
  onChange={...}
/>

RadioGroup

RadioGroup مجموعه‌ای از Radio ها را با یک name مشترک رندر می‌کند و انتخاب بین آن‌ها را خودکار مدیریت می‌کند؛ نیازی نیست برای هر دکمه checked ست کنی، فقط value گروه را کنترل کن.

اگر کنترل بیشتری نیاز داری (مثلاً چیدمان سفارشی یا جدا کردن گزینه‌ها)، می‌توانی مستقیماً از Radio استفاده کنی:

<Radio
  name="plan"
  value="pro"
  label="حرفه‌ای"
  checked={plan === "pro"}
  onChange={() => setPlan("pro")}
/>

برای حالت uncontrolled می‌توانی از defaultChecked در Radio native استفاده کنی:

<Radio name="delivery" value="express" label="ارسال فوری" defaultChecked />
<Radio name="delivery" value="normal" label="ارسال عادی" />

Use in Form

RadioGroup مقدار انتخاب‌شده را از طریق onChange تحویل می‌دهد:

function ShippingForm() {
  const [method, setMethod] = useState("normal");

  function handleSubmit(event) {
    event.preventDefault();
    console.log({ method });
  }

  return (
    <form onSubmit={handleSubmit}>
      <RadioGroup
        name="shipping"
        value={method}
        onChange={setMethod}
        options={[
          { value: "normal", label: "ارسال عادی" },
          { value: "express", label: "ارسال فوری" },
        ]}
      />
      <button type="submit">ادامه</button>
    </form>
  );
}

Accessibility

• Radio به‌صورت خودکار یک id منحصربه‌فرد (با useId) تولید می‌کند و label را با htmlFor به input متصل می‌کند، پس کلیک روی متن هم دکمه را انتخاب می‌کند.
• name مشترک باعث می‌شود گروه با صفحه‌کلید قابل پیمایش باشد (Tab برای ورود به گروه، Arrow برای جابه‌جایی بین گزینه‌ها).
• برای توضیح گروه، یک heading یا fieldset و legend مناسب اطراف گزینه‌ها قرار بده.

Data Attributes and Customize CSS

Radio و RadioGroup hookهای پایدار زیر را تولید می‌کنند:

<div data-fara-radio-group>
  <label data-fara-radio>
    <input data-fara-radio-input type="radio" />
    گزینه
  </label>
</div>

Attribute	کاربرد
data-fara-radio-group	wrapper گروه
data-fara-radio	wrapper هر گزینه
data-fara-radio-input	خود input رادیو

className در Radio روی label بیرونی اعمال می‌شود؛ RadioGroup در API فعلی className ندارد:

<Radio className="featured-plan" name="plan" value="pro" label="حرفه‌ای" />

[data-fara-radio-group] {
  display: grid;
  gap: 12px;
}

.featured-plan {
  font-weight: 700;
}

[data-fara-radio-input]:checked {
  accent-color: #7c3aed;
}

Props — Radio

Prop	Type	Default	Description
label	ReactNode	-	متن یا محتوای کنار دکمه
className	string	-	کلاس CSS اضافی برای سفارشی‌سازی (روی label بیرونی اعمال می‌شود)
ref	Ref<HTMLInputElement>	-	دسترسی مستقیم به المان DOM دکمه

علاوه بر موارد بالا، تمام ویژگی‌های استاندارد <input type="radio"> (مثل name, value, checked, onChange, disabled, aria-* و ...) نیز پشتیبانی می‌شوند.

Props — RadioGroup

Prop	Type	Default	Description
name	string	-	نام مشترک گروه (الزامی)
options	RadioOption[]	-	آرایه‌ی گزینه‌ها (الزامی)
value	string	-	مقدار انتخاب‌شده (controlled)
onChange	(value: string) => void	-	هنگام انتخاب یک گزینه صدا زده می‌شود
disabled	boolean	false	غیرفعال کردن تمام گزینه‌های گروه

interface RadioOption {
  value: string;
  label: string;
}