Switch

کامپوننت Switch برای روشن/خاموش کردن یک گزینه‌ی مستقل استفاده می‌شود؛ مثل فعال‌سازی اعلان‌ها یا حالت تاریک. برخلاف Checkbox که برای انتخاب است، Switch بلافاصله اثر خود را اعمال می‌کند و مثل یک کلید عمل می‌کند.

Import

import { Switch } from "fara-ui";

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

Basic Usage

import { Switch } from "fara-ui";

<Switch label="اعلان‌ها" defaultChecked />;

Playground

اعلان‌ها

label

checked

disabled

<Switch label="اعلان‌ها" onChange={...} />

Controlled vs Uncontrolled

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

import { useState } from "react";

function NotificationsSetting() {
  const [enabled, setEnabled] = useState(false);

  return (
    <Switch
      label={enabled ? "اعلان‌ها فعال است" : "اعلان‌ها خاموش است"}
      checked={enabled}
      onChange={(event) => setEnabled(event.target.checked)}
    />
  );
}

در حالت uncontrolled، مقدار اولیه را با defaultChecked تعیین کن:

<Switch label="حالت تاریک" defaultChecked />

checked و defaultChecked را هم‌زمان استفاده نکن؛ مانند inputهای native، یکی از این دو الگو را انتخاب کن.

Custom Label

label از نوع ReactNode است، بنابراین می‌توانی متن یا محتوای React به آن بدهی:

<Switch
  label={
    <span>
      دریافت خبرنامه <small>(هفتگی)</small>
    </span>
  }
/>

Accessibility

• کامپوننت روی input بومی با role="switch" قرار گرفته و با صفحه‌کلید (Tab, Space) قابل استفاده است.
• به‌صورت خودکار یک id منحصربه‌فرد (با useId) تولید می‌کند و label را با htmlFor به input متصل می‌کند، پس کلیک روی متن هم سوییچ را فعال می‌کند.

Data Attributes and Customize CSS

ساختار پایدار کامپوننت با این attributeها قابل هدف‌گیری است:

Attribute	کاربرد
data-fara-switch	label ریشه
data-fara-switch-input	input بومی checkbox با role switch
data-fara-switch-track	مسیر ظاهری سوییچ
data-fara-switch-thumb	thumb داخلی

<Switch className="settings-switch" label="اعلان‌ها" />

.settings-switch {
  gap: 10px;
}

[data-fara-switch-input]:checked + [data-fara-switch-track] {
  background: #16a34a;
}

[data-fara-switch-input]:checked + [data-fara-switch-track] [data-fara-switch-thumb] {
  transform: translateX(100%);
}

[data-fara-switch-input]:disabled + [data-fara-switch-track] {
  opacity: 0.5;
}

className برای تغییر layout یا یک نمونه‌ی خاص مناسب است؛ برای حالت checked از selector رسمی input و track استفاده کن.

Props

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

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