> ## 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.

# شريط التمرير

> اختر قيمة رقمية أو نطاقًا باستخدام مقابض قابلة للسحب ويمكن الوصول إليها عبر لوحة المفاتيح.

## نظرة عامة

يدعم `Slider` رقمًا واحدًا أو مصفوفة من الأرقام لنطاق. أنشئ التسمية والمسار والمؤشر والمقابض داخله `Root`.

**Light**

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

**Dark**

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

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

## استخدام

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

استخدم `defaultValue` لتعيين مستوى الصوت الأولي. يتولى شريط التمرير التغييرات اللاحقة.

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

export const VolumeSlider = () => (
  <Slider.Root name="volume" defaultValue={40} min={0} max={100} step={1}>
    <Text
      render={<div />}
      style={{ display: 'flex', justifyContent: 'space-between' }}
    >
      <Slider.Label>Volume</Slider.Label>
      <Slider.Value />
    </Text>
    <Slider.Control>
      <Slider.Track>
        <Slider.Indicator />
        <Slider.Thumb />
      </Slider.Track>
    </Slider.Control>
  </Slider.Root>
);
```

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

قارن بين ألوان التمييز والنجاح عند القيم الدنيا والوسطى والقصوى وقيم التعطيل. تظل أشرطة التمرير المفعّلة تفاعلية.

**Light**

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

**Dark**

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

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

## البنية التشريحية العربية

ضع المسار والمقابض داخل `Slider.Control`، الذي يتعامل مع تفاعل المؤشر. تُظهر هذه الشجرة شريط تمرير بمقبض واحد.

```text theme={null}
Slider.Root
├── Slider.Label
├── Slider.Value
└── Slider.Control
    └── Slider.Track
        ├── Slider.Indicator
        └── Slider.Thumb
```

| الجزء | المتطلبة | الغرض |
| - | - | - |
| `Root` | مطلوب | يملك القيمة والحدود والخطوة والاتجاه. |
| `Control` | مطلوب | يتعامل مع تفاعل المؤشر ويحدّد مواضع المقابض. |
| `Track` | مطلوب للمسار المنسّق | يعرض نطاق القيم الكامل. |
| `Thumb` | واحد لكل قيمة قابلة للضبط | يوفّر مقبضًا قابلاً للتركيز مع تفاعل عبر لوحة المفاتيح. |
| `Label` | مُوصى به | يوفّر تسمية مرئية؛ يحتاج كل مقبض إلى اسم يمكن الوصول إليه. |
| `القيمة` | اختياري | يعرض القيمة الرقمية الحالية. |
| `Indicator` | اختياري | يعرض الجزء المحدد من المسار. |

للنطاق، أضف مقبضًا لكل قيمة مع `index` المطابق لها واسم مميز يمكن الوصول إليه. تبقى التسميات والمخرجات الرقمية خارج `Control`، كي لا تصبح جزءًا من المنطقة القابلة للسحب.

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

مرر `value` وحدّثه باستخدام `onValueChange` لتتولى التحكم في مستوى الصوت نفسه ضمن حالة React. تتلقى دالة الاستدعاء القيمة التالية وتفاصيل الحدث.

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

export const VolumeSlider = () => {
  const [volume, setVolume] = useState(40);

  return (
    <Slider.Root
      name="volume"
      value={volume}
      onValueChange={setVolume}
      min={0}
      max={100}
      step={1}
    >
      <Slider.Label>Volume</Slider.Label>
      <Slider.Value />
      <Slider.Control>
        <Slider.Track>
          <Slider.Indicator />
          <Slider.Thumb />
        </Slider.Track>
      </Slider.Control>
    </Slider.Root>
  );
};
```

استخدم `onValueChange` لإبقاء القيمة المتحكم بها محدّثة أثناء التفاعل. يتعامل `onValueCommitted` مع القيمة النهائية عند انتهاء التفاعل، لحفظها على سبيل المثال. تتوفر دالتا الاستدعاء أيضًا في الوضع غير المتحكم به دون تولي التحكم في القيمة.

تتضمن تفاصيل التغيير `event` المصدر، و`reason` التفاعل، و`activeThumbIndex`، و`cancel()`. تستخدم تفاصيل الالتزام عقد الأحداث العام لـ Base UI ولا تتضمن إلغاء التغيير. لا يتم الالتزام بالتغيير المُلغى.

## النطاق

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

export const PriceRange = () => (
  <Slider.Root
    defaultValue={[25, 75]}
    min={0}
    max={100}
    minStepsBetweenValues={10}
  >
    <Slider.Label>Price range</Slider.Label>
    <Slider.Value />
    <Slider.Control>
      <Slider.Track>
        <Slider.Indicator />
        <Slider.Thumb index={0} aria-label="Minimum price" />
        <Slider.Thumb index={1} aria-label="Maximum price" />
      </Slider.Track>
    </Slider.Control>
  </Slider.Root>
);
```

امنح مقابض النطاق أسماء مميزة يمكن الوصول إليها و`index` يتوافق مع قيمتها. يعيّن `minStepsBetweenValues` الحد الأدنى للفجوة بالخطوات. نوع القيمة العام للجذر هو رقم أو مصفوفة أرقام للقراءة فقط.

للتحكم في نطاق، خزّن المصفوفة في حالة React ومررها عبر `value` و`onValueChange`، تمامًا كما في القيمة المفردة.

## لوحة المفاتيح والمظهر

تضبط مفاتيح الأسهم مقبضًا محددًا بخطوة واحدة. ينقل مفتاحا Home وEnd المقبض نحو الحدود مع مراعاة قيود النطاق. يغيّر `orientation="vertical"` التخطيط واتجاه لوحة المفاتيح. استخدم `disabled` على `Root` لمنع التغييرات.

عيّن `color="success"` للوحة الألوان البديلة؛ والافتراضي هو `accent`.

القيمة الافتراضية لـ `thumbAlignment` هي `edge`. مرر `center` أو `edge-client-only` لتجاوزها. تظل تركيبة `className` و`style` و`render` الأصلية متاحة في كل جزء، بما في ذلك دوال الحالة.

> [!NOTE]
>
> باستخدام محاذاة `edge` و`edge-client-only`، لا يعيد Base UI 1.8 و1.9 أبدًا
> قياس مقبض بعد تغيير حجم `Slider.Control`، ويحتفظ شريط التمرير الذي يتم تحميله
> أثناء إخفائه بمقابضه مخفيةً عند إظهاره
> ([mui/base-ui#5995](https://github.com/mui/base-ui/issues/5995)). تواجه مكوّنات واجهة React
> المشكلة نفسها عند تصييرها الأول. استخدم
> `thumbAlignment="center"` إلى أن يتضمن إصدار من Base UI الإصلاح
> ([mui/base-ui#6000](https://github.com/mui/base-ui/pull/6000)).

## التكامل والأنواع الأصلية

يستنتج `Slider.Root` رقماً أو مصفوفة أرقام للقراءة فقط من `value` أو `defaultValue`، مع الاحتفاظ بهذا النوع في كلا الاستدعاين. يقبل `SliderRootProps` كليهما افتراضياً؛ استخدم `SliderRootProps\<number>` للمساعدات ذات القيمة الواحدة أو `SliderRootProps\<readonly number[]>` للمساعدات الخاصة بالنطاق.

لكل جزء نوع خصائص مُصدَّر في `twenty-ui/primitives/input`: `SliderRootProps` و`SliderControlProps` و`SliderTrackProps` و`SliderIndicatorProps` و`SliderThumbProps` و`SliderLabelProps` و`SliderValueProps`.

تستهدف المراجع عناصر div لـ Root وControl وTrack وIndicator وThumb وLabel، وعنصر output لـ Value. يستهدف مرجع Thumb مقبضه المرئي؛ وينتمي اسمه المتاح وقيمة النموذج الأصلية الخاصة به إلى إدخال النطاق المتداخل. استخدم `name` و`form` على Root للإرسال الأصلي، مع إدخال واحد لكل قيمة نطاق.

## الإزاحة

يُنشأ المرجع من أنواع المكونات العامة. تُقبل أيضًا السمات الأصلية، بما في ذلك الأسماء التي يمكن الوصول إليها ومعالجات الأحداث، على الأجزاء التي تعرض عناصر.

### Slider.Root

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

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

**Root.color** `"accent" | "success"` (default: accent)

Color of the indicator and thumbs.

**Root.defaultValue** `number | readonly number[]`

The uncontrolled value of the slider when it's initially rendered.

To render a controlled slider, use the `value` prop instead.

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

Whether the slider should ignore user interaction.

**Root.form** `string`

Identifies the form that owns the slider inputs.
Useful when the slider is rendered outside the form.

**Root.format** `NumberFormatOptions`

Options to format the value.

**Root.largeStep** `number` (default: 10)

The granularity with which the slider can step through values when using Page Up/Page Down or Shift + Arrow Up/Arrow Down.

**Root.locale** `LocalesArgument`

The locale used by `Intl.NumberFormat` when formatting the value.
Defaults to the user's runtime locale.

**Root.max** `number` (default: 100)

The maximum allowed value of the slider.
Should not be equal to min.

**Root.min** `number` (default: 0)

The minimum allowed value of the slider.
Should not be equal to max.

**Root.minStepsBetweenValues** `number` (default: 0)

The minimum steps between values in a range slider.

**Root.name** `string`

Identifies the field when a form is submitted.

**Root.onValueChange** `((value: TValue extends number ? number : TValue, eventDetails: SliderRootChangeEventDetails) =\> void)`

Callback function that is fired when the slider's value changed.
Receives the new value as the first argument; the originating event is
available as `eventDetails.event`. The value is also reflected on
`eventDetails.event.target.value` for form integration.

The `eventDetails.reason` indicates what triggered the change:

* `'input-change'` when the hidden range input emits a change event (for example, via form integration)
* `'track-press'` when the control track is pressed
* `'drag'` while dragging a thumb
* `'keyboard'` for keyboard input
* `'none'` when the change is triggered without a specific interaction

**Root.onValueCommitted** `((value: TValue extends number ? number : TValue, eventDetails: SliderRootCommitEventDetails) =\> void)`

Callback function that is fired when a value change is committed.
Does not fire if the value did not change, or if the change was canceled.
**Warning**: This is a generic event, not a change event.

The `eventDetails.reason` indicates what triggered the commit:

* `'drag'` while dragging a thumb
* `'track-press'` when the control track is pressed
* `'keyboard'` for keyboard input
* `'input-change'` when the hidden range input emits a change event (for example, via form integration)
* `'none'` when the commit occurs without a specific interaction

**Root.orientation** `"horizontal" | "vertical"` (default: horizontal)

The component orientation.

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

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.step** `number` (default: 1)

The granularity with which the slider can step through values. (A "discrete" slider.)
The `min` prop serves as the origin for the valid values.
We recommend (max - min) to be evenly divisible by the step.

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

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

**Root.thumbAlignment** `"center" | "edge-client-only" | "edge"` (default: edge)

How the thumb(s) are aligned relative to `Slider.Control` when the value is at `min` or `max`:

* `center`: The center of the thumb is aligned with the control edge
* `edge`: The thumb is inset within the control such that its edge is aligned with the control edge
* `edge-client-only`: Same as `edge` but renders after React hydration on the client, reducing bundle size in return

**Root.thumbCollisionBehavior** `"none" | "push" | "swap"` (default: push)

Controls how thumbs behave when they collide during pointer interactions.

* `'push'` (default): Thumbs push each other without restoring their previous positions when dragged back.
* `'swap'`: Thumbs swap places when dragged past each other.
* `'none'`: Thumbs cannot move past each other; excess movement is ignored.

**Root.value** `number | readonly number[]`

The value of the slider.
For range sliders, provide an array with one value per thumb.

### Slider.Control

**Control.className** `string | ((state: SliderControlState) =\> string | undefined)`

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

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

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.

**Control.style** `CSSProperties | ((state: SliderControlState) =\> CSSProperties | undefined)`

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

### Slider.Track

**Track.className** `string | ((state: SliderTrackState) =\> string | undefined)`

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

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

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.

**Track.style** `CSSProperties | ((state: SliderTrackState) =\> CSSProperties | undefined)`

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

### Slider.Indicator

**Indicator.className** `string | ((state: SliderIndicatorState) =\> string | undefined)`

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

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

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.

**Indicator.style** `CSSProperties | ((state: SliderIndicatorState) =\> CSSProperties | undefined)`

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

### Slider.Thumb

**Thumb.aria-valuetext** `string`

A string value forwarded to the [`aria-valuetext`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) attribute of the `input`.
Ignored when `getAriaValueText` is provided.

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

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

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

Whether the thumb should ignore user interaction.

**Thumb.getAriaLabel** `((index: number) =\> string) | null`

A function which returns a string value for the [`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute of the `input`.

**Thumb.getAriaValueText** `((formattedValue: string, value: number, index: number) =\> string) | null`

A function which returns a string value for the [`aria-valuetext`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) attribute of the `input`.
This is important for screen reader users.

**Thumb.index** `number`

The index of the thumb which corresponds to the index of its value in the
`value` or `defaultValue` array.
This prop is required to support server-side rendering for range sliders
with multiple thumbs.

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

A ref to access the nested input element.

**Thumb.onBlur** `FocusEventHandler\<HTMLInputElement\>`

A blur handler forwarded to the `input`.

**Thumb.onFocus** `FocusEventHandler\<HTMLInputElement\>`

A focus handler forwarded to the `input`.

**Thumb.onKeyDown** `KeyboardEventHandler\<HTMLInputElement\>`

A keydown handler forwarded to the `input`.

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

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: SliderThumbState) =\> CSSProperties | undefined)`

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

**Thumb.tabIndex** `number`

Optional tab index attribute forwarded to the `input`.

### Slider.Label

**Label.className** `string | ((state: SliderRootState) =\> string | undefined)`

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

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

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.

**Label.style** `CSSProperties | ((state: SliderRootState) =\> CSSProperties | undefined)`

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

### Slider.Value

**Value.className** `string | ((state: SliderValueState) =\> string | undefined)`

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

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

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.

**Value.style** `CSSProperties | ((state: SliderValueState) =\> 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.