> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# المفتاح

> عنصر تحكم مُسمّى للتشغيل أو الإيقاف بحالة متحكَّم بها أو غير متحكَّم بها.

## نظرة عامة

استخدم `Switch` لتفضيل التشغيل أو الإيقاف. امنح عنصر التحكم تسمية مرئية أو اسمًا يمكن الوصول إليه.

**Light**

[مثال على المفتاح (light)](https://storybook.twenty.com/iframe.html?id=ui-input-switch-switch--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[مثال على المفتاح (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-switch-switch--display\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-switch-switch--display)

## استخدام

### حالة غير متحكَّم بها

استخدم `defaultChecked` لتعيين حالة التحديد الأولية. يمتلك المفتاح التبديل التغييرات اللاحقة.

```tsx theme={null}
import { useId } from 'react';
import { Switch } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';

export const NotificationsPreference = () => {
  const switchId = useId();

  return (
    <label
      htmlFor={switchId}
      style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}
    >
      <Switch id={switchId} name="notifications" />
      <Text render={<span />}>Email notifications</Text>
    </label>
  );
};
```

## الخيارات المرئية

قارن بين الحجمين في حالات التشغيل والإيقاف والتعطيل والقراءة فقط والتركيز. استخدم الأمثلة المفعّلة لتجربة التبديل.

**Light**

[الخيارات المرئية لمفتاح التبديل (light)](https://storybook.twenty.com/iframe.html?id=ui-input-switch-switch--catalog\&viewMode=story\&globals=colorScheme:light)

**Dark**

[الخيارات المرئية لمفتاح التبديل (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-switch-switch--catalog\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-switch-switch--catalog)

## حالة متحكَّم بها

مرّر `checked` وحدّثه باستخدام `onCheckedChange` لامتلاك التفضيل نفسه في حالة React.

```tsx theme={null}
import { useId, useState } from 'react';
import { Switch } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';

export const NotificationsPreference = () => {
  const switchId = useId();
  const [checked, setChecked] = useState(false);

  return (
    <label
      htmlFor={switchId}
      style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}
    >
      <Switch
        id={switchId}
        name="notifications"
        checked={checked}
        onCheckedChange={setChecked}
      />
      <Text render={<span />}>Email notifications</Text>
    </label>
  );
};
```

يتلقى `onCheckedChange` القيمة المنطقية التالية وتفاصيل الحدث. تقبل الخاصية `size` القيمة `sm` أو `md`، وتكون قيمتها الافتراضية `md`.

لصف بعرض كامل ومتسق يتضمن أيقونة ووصفًا ومفتاح تبديل، استخدم [SettingsRow](https://docs.twenty.com/ar/ui/components/settings/settings-row.md).

## لوحة المفاتيح والنماذج

ينقل مفتاح Tab التركيز إلى المفتاح، ويبدّله مفتاح Space. يؤدي النقر على التسمية المرتبطة به أيضًا إلى تبديله. استخدم `disabled` لمنع التفاعل أو `readOnly` للإبقاء على عنصر تحكم قابل للتركيز لا يمكن تغيير قيمته.

يرسل المفتاح المُسمّى قيمته عند تحديده. استخدم `value` لتخصيص تلك القيمة، واستخدم `uncheckedValue` إذا كان يجب أن يرسل النموذج أيضًا قيمة عندما يكون في وضع الإيقاف.

## الأجزاء والمحتوى المخصص

يجمع `Switch` الجذر المصمم ومقبضه الافتراضي. استخدم `Switch.Root` مع `Switch.Thumb` لتملك محتوى المقبض. يدير Root الحالة ومظهر المسار؛ ويعرض Thumb المحتوى الذي توفره.

```tsx theme={null}
import { Switch } from 'twenty-ui/primitives/input';

export const CustomPreference = () => (
  <Switch.Root aria-label="Updates" defaultChecked>
    <Switch.Thumb></Switch.Thumb>
  </Switch.Root>
);
```

`SwitchRootProps` و`SwitchThumbProps` نوعان عامان مُصدَّران من `twenty-ui/primitives/input`. يقبل كلا الجزأين السمات الأصلية والمعالجات والمراجع و`render` وعمليات الاستدعاء `className` و`style` المستندة إلى الحالة. يستهدف `ref` الخاص بـ Root عنصر التحكم المرئي؛ ويستهدف `inputRef` حقل الإدخال الأصلي. يستهدف مرجع الجزء العنصر الذي يعرضه. مرر `nativeButton` مع `render={<button />}` عند استبدال Root بزر. تنتمي خصائص المظهر إلى Root؛ وتُدمج الفئات والأنماط الصريحة مع الإعدادات الافتراضية.

يتلقى Thumb حالة checked وdisabled وreadOnly وrequired وField الحالية. يتبع موضعه اتجاه القراءة.

**Light**

[تركيب جزء Switch (light)](https://storybook.twenty.com/iframe.html?id=ui-input-switch-parts--composition\&viewMode=story\&globals=colorScheme:light)

**Dark**

[تركيب جزء Switch (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-switch-parts--composition\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-switch-parts--composition)

تظل التجميعة القابلة للاستدعاء ونوع `SwitchProps` الخاص بها مدعومين. استبدل التجميعة بـ Root وجزئه عند توفير محتوى مقبض مخصص بدلًا من إلحاق جزء آخر بأبناء التجميعة.

لإعادة تعيين نموذج متحكم به، عالج `onReset` الخاص بالنموذج وأعد `checked` إلى قيمتك الأولية. لا يستعيد Base UI 1.8 حالة المكونات غير المتحكم بها عند إعادة تعيين النموذج الأصلية. تحافظ `required` و`form` و`value` و`uncheckedValue` على سلوك حقل الإدخال الأصلي المصدر.

## الإزاحة

يتضمن المرجع خصائص خاصة بالمكوّن وخصائص Base UI الموروثة. تُقبل أيضًا السمات الأصلية مثل `aria-label` و`data-*`.

**checked** `boolean`

Whether the switch is currently active.

To render an uncontrolled switch, use the `defaultChecked` prop instead.

**className** `string | ((state: SwitchRootState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**defaultChecked** `boolean` (default: false)

Whether the switch is initially active.

To render a controlled switch, use the `checked` prop instead.

**disabled** `boolean` (default: false)

Whether the component should ignore user interaction.

**form** `string`

Identifies the form that owns the hidden input.
Useful when the switch is rendered outside the form.

**id** `string`

The id of the hidden input element.

When `nativeButton` is `true`, the id is applied to the root element.

**inputRef** `Ref\<HTMLInputElement\>`

A ref to access the hidden `<input>` element.

**name** `string`

Identifies the field when a form is submitted.

**nativeButton** `boolean` (default: false)

Whether the component renders a native `<button>` element when replacing it
via the `render` prop.
Set to `true` if the rendered element is a native button.

**onCheckedChange** `((checked: boolean, eventDetails: \{ reason: "none"; event: Event; cancel: () =\> void; allowPropagation: () =\> void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; \}) =\> void)`

Event handler called when the switch is activated or deactivated.

**readOnly** `boolean` (default: false)

Whether the user should be unable to activate or deactivate the switch.

**render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, SwitchRootState\>`

Allows you to replace the component's HTML element
with a different tag, or compose it with another component.

Accepts a `ReactElement` or a function that returns the element to render.

**required** `boolean` (default: false)

Whether the user must activate the switch before submitting a form.

**size** `"md" | "sm"` (default: md)

Visual size of the switch.

**style** `CSSProperties | ((state: SwitchRootState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

**uncheckedValue** `string`

The value submitted with the form when the switch is off.
By default, unchecked switches do not submit any value, matching native checkbox behavior.

**value** `string`

The value submitted with the form when the switch is on.
By default, switch submits the "on" value, matching native checkbox behavior.

### Switch.Root

**Root.checked** `boolean`

Whether the switch is currently active.

To render an uncontrolled switch, use the `defaultChecked` prop instead.

**Root.className** `string | ((state: SwitchRootState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Root.defaultChecked** `boolean` (default: false)

Whether the switch is initially active.

To render a controlled switch, use the `checked` prop instead.

**Root.disabled** `boolean` (default: false)

Whether the component should ignore user interaction.

**Root.form** `string`

Identifies the form that owns the hidden input.
Useful when the switch is rendered outside the form.

**Root.id** `string`

The id of the hidden input element.

When `nativeButton` is `true`, the id is applied to the root element.

**Root.inputRef** `Ref\<HTMLInputElement\>`

A ref to access the hidden `<input>` element.

**Root.name** `string`

Identifies the field when a form is submitted.

**Root.nativeButton** `boolean` (default: false)

Whether the component renders a native `<button>` element when replacing it
via the `render` prop.
Set to `true` if the rendered element is a native button.

**Root.onCheckedChange** `((checked: boolean, eventDetails: \{ reason: "none"; event: Event; cancel: () =\> void; allowPropagation: () =\> void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; \}) =\> void)`

Event handler called when the switch is activated or deactivated.

**Root.readOnly** `boolean` (default: false)

Whether the user should be unable to activate or deactivate the switch.

**Root.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, SwitchRootState\>`

Allows you to replace the component's HTML element
with a different tag, or compose it with another component.

Accepts a `ReactElement` or a function that returns the element to render.

**Root.required** `boolean` (default: false)

Whether the user must activate the switch before submitting a form.

**Root.size** `"md" | "sm"` (default: md)

Visual size of the switch.

**Root.style** `CSSProperties | ((state: SwitchRootState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

**Root.uncheckedValue** `string`

The value submitted with the form when the switch is off.
By default, unchecked switches do not submit any value, matching native checkbox behavior.

**Root.value** `string`

The value submitted with the form when the switch is on.
By default, switch submits the "on" value, matching native checkbox behavior.

### Switch.Thumb

**Thumb.className** `string | ((state: SwitchThumbState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Thumb.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, SwitchThumbState\>`

Allows you to replace the component's HTML element
with a different tag, or compose it with another component.

Accepts a `ReactElement` or a function that returns the element to render.

**Thumb.style** `CSSProperties | ((state: SwitchThumbState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.