Checkbox

کامپوننت Checkbox برای انتخاب یک یا چند گزینه از میان چند گزینه‌ی مستقل از هم استفاده می‌شود؛ مثل تیک زدن موافقت با قوانین یا انتخاب چند فیلتر هم‌زمان.

Import

import { Checkbox } from "fara-ui";

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

Basic Usage

import { Checkbox } from "fara-ui";

export function TermsCheckbox() {
  return <Checkbox label="با قوانین و شرایط استفاده موافقم" />;
}

label می‌تواند متن یا هر محتوای React باشد:

<Checkbox
  label={
    <span>
      با <a href="/terms">قوانین استفاده</a> موافقم
    </span>
  }
/>

Playground

با قوانین موافقم

label

checked

disabled

<Checkbox label="با قوانین موافقم" onChange={...} />

Controlled vs Uncontrolled

مثل هر input استاندارد دیگری، Checkbox هم می‌تواند controlled (با checked و onChange) یا uncontrolled (با defaultChecked) استفاده شود.

import { useState } from "react";

export function ControlledCheckbox() {
  const [checked, setChecked] = useState(false);

  return (
    <div>
      <Checkbox
        label="با قوانین موافقم"
        checked={checked}
        onChange={(event) => setChecked(event.target.checked)}
      />
      <p>وضعیت: {checked ? "فعال" : "غیرفعال"}</p>
    </div>
  );
}

اگر لازم نیست state را در React نگه داری، از حالت uncontrolled استفاده کن:

<Checkbox
  label="دریافت خبرنامه"
  defaultChecked
  onChange={(event) => {
    console.log("checked:", event.target.checked);
  }}
/>

Use in Form

چون کامپوننت بر پایه‌ی <input type="checkbox"> ساخته شده، می‌توانی از name و value برای ارسال فرم استفاده کنی:

function PreferencesForm() {
  function handleSubmit(event) {
    event.preventDefault();
    const form = new FormData(event.currentTarget);
    console.log(form.get("notifications"));
  }

  return (
    <form onSubmit={handleSubmit}>
      <Checkbox name="notifications" value="email" label="ارسال اعلان‌های ایمیلی" />
      <button type="submit">ذخیره</button>
    </form>
  );
}

برای اجباری‌کردن تیک‌زدن، از required استفاده کن:

<Checkbox label="قوانین را خوانده‌ام و می‌پذیرم" required />

Accessibility

• کامپوننت به‌صورت خودکار یک id منحصربه‌فرد (با useId) تولید می‌کند و label را با htmlFor به input متصل می‌کند، پس کلیک روی متن هم چک‌باکس را فعال می‌کند.
• اگر خودت id سفارشی پاس بدهی، همان استفاده می‌شود.
• برای گروهی از چک‌باکس‌ها، یک عنوان یا fieldset مناسب اضافه کن تا ارتباط گزینه‌ها برای screen reader روشن باشد.

Data Attributes and Customize CSS

برای هدف‌گرفتن ساختار Checkbox از hookهای پایدار data-fara-* استفاده کن:

<label data-fara-checkbox>
  <input data-fara-checkbox-input type="checkbox" />
  متن گزینه
</label>

Attribute	عنصر	کاربرد
data-fara-checkbox	label بیرونی	شناسایی wrapper کامپوننت
data-fara-checkbox-input	input داخلی	هدف‌گرفتن خود checkbox

برای یک نمونه‌ی خاص، className روی label بیرونی اعمال می‌شود:

<Checkbox className="marketing-checkbox" label="دریافت ایمیل‌های تبلیغاتی" />

.marketing-checkbox {
  color: #334155;
  gap: 12px;
}

برای سفارشی‌سازی سراسری یا مبتنی بر ساختار، از data attribute استفاده کن:

[data-fara-checkbox] {
  align-items: flex-start;
}

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

[data-fara-checkbox-input]:disabled {
  cursor: not-allowed;
}

برای overrideهای پایدار به کلاس‌های داخلی CSS Modules وابسته نشو.

Props

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

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