Slider

کامپوننت Slider برای انتخاب یک عدد (یا بازه‌ای از اعداد) از یک محدوده‌ی پیوسته استفاده می‌شود؛ مثل تنظیم قیمت، صدا یا اعمال فیلتر بازه‌ای. با فعال‌کردن range دو دستگیره نمایش داده می‌شود و کاربر می‌تواند یک بازه انتخاب کند.

Import

import { Slider } from "fara-ui";

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

Basic Usage

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

export function VolumeSlider() {
  const [volume, setVolume] = useState(50);

  return (
    <Slider value={volume} min={0} max={100} label="میزان صدا" showValue onChange={setVolume} />
  );
}

Playground

میزان صدا40

value

min

max

step

label

showValue

disabled

<Slider
  value={40}
  min={0}
  max={100}
  step={1}
  label="میزان صدا"
  showValue
  onChange={...}
/>

Range Mode

با پرچم range مقدار از یک عدد به شیء { min, max } تبدیل می‌شود:

const [price, setPrice] = useState({ min: 20, max: 80 });

<Slider range value={price} min={0} max={100} showValue label="محدوده قیمت" onChange={setPrice} />;

onChange در این حالت شیء جدیدی با همین شکل دریافت می‌کند و ترتیب min ≤ max همیشه حفظ می‌شود:

function PriceFilter() {
  const [price, setPrice] = useState({ min: 20, max: 80 });

  return (
    <Slider
      range
      value={price}
      onChange={setPrice}
      formatValue={(value) => `${value.toLocaleString("fa-IR")} تومان`}
      showValue
    />
  );
}

Formatting the Value

با formatValue می‌توانی مقدار نمایش‌داده‌شده در برچسب را سفارشی کنی؛ مثلاً افزودن واحد تومان:

<Slider
  value={price}
  onChange={setPrice}
  showValue
  formatValue={(v) => `${v.toLocaleString("fa-IR")} تومان`}
/>

Accessibility

• در حالت معمولی، یک <input type="range"> در کامپوننت قرار دارد و با Tab و کلیدهای جهت قابل استفاده است.
• اگر label پاس بدهی، همان مقدار به‌صورت aria-label روی input اعمال می‌شود.
• در حالت range، دو thumb با pointer قابل جابه‌جایی هستند و input داخلی از ترتیب Tab خارج می‌شود؛ برای کنترل keyboard مستقلِ هر thumb، این کامپوننت را با یک الگوی دسترس‌پذیر سفارشی تکمیل کن.
• برای کاربران صفحه‌خوان، همیشه label معنادار بده و مقدار را با showValue یا متن اطراف کنترل نمایش بده.

Data Attributes and Customize CSS

Slider hookهای زیر را ارائه می‌کند:

Attribute	کاربرد
data-fara-slider	ریشه‌ی اسلایدر
data-range	روی ریشه در حالت بازه‌ای
data-disabled	روی ریشه هنگام غیرفعال بودن
data-fara-slider-label-row	ردیف label و مقدار
data-fara-slider-value	متن مقدار نمایشی
data-fara-slider-track	مسیر تعامل pointer
data-fara-slider-fill	بخش پرشده‌ی مسیر
data-fara-slider-thumb	هر دستگیره
data-handle	نوع دستگیره: min یا max
data-active	دستگیره‌ی در حال drag
data-fara-slider-input	input بومی داخلی

<Slider className="price-slider" value={50} onChange={setPrice} />

.price-slider {
  max-width: 360px;
}

[data-fara-slider-fill] {
  background: #2563eb;
}

[data-fara-slider-thumb][data-active] {
  outline: 3px solid rgb(37 99 235 / 25%);
}

[data-fara-slider][data-disabled] {
  opacity: 0.5;
}

track با dir="ltr" رندر می‌شود تا رابطه‌ی مقدار و موقعیت همیشه ثابت بماند؛ در صفحه‌ی RTL نیز این رفتار را با CSS معکوس نکن.

Props

Prop	Type	Default	Description
value	number | SliderRangeValue	-	مقدار فعلی (الزامی، controlled)
onChange	(value) => void	-	هنگام تغییر مقدار صدا زده می‌شود (الزامی)
range	true	-	فعال‌سازی حالت بازه‌ای (دو دستگیره)
min	number	0	حد پایین محدوده
max	number	100	حد بالای محدوده
step	number	1	گام تغییر مقدار
showValue	boolean	false	نمایش مقدار فعلی کنار برچسب
label	string	-	برچسب اسلایدر
formatValue	(value: number) => string	-	قالب‌بندی مقدار نمایش‌داده‌شده
disabled	boolean	false	غیرفعال کردن اسلایدر
className	string	-	کلاس CSS اضافی برای سفارشی‌سازی
ref	Ref<HTMLInputElement>	-	دسترسی مستقیم به input مخفی

interface SliderRangeValue {
  min: number;
  max: number;
}