اسلایدر (Slider)

ورودی که به کاربر امکان می‌دهد مقداری را در بازه مشخص انتخاب کند.

نصب (Installation)

1npx @quark-lab/rad-ui add slider

نمونه‌ها (Examples)

استفاده پایه (Basic Usage)

استفاده ساده از اسلایدر.

مشاهده کد
1import { Slider } from "@/components/ui/slider";
2
3export default function BasicExample() {
4  return (
5    <Slider defaultValue={[33]} max={100} step={1} />
6  );
7}
8

با برچسب (With Label)

استفاده از اسلایدر همراه با برچسب.

مشاهده کد
1import { Slider } from "@/components/ui/slider";
2import { Label } from "@/components/ui/label";
3
4export default function WithLabelExample() {
5  return (
6    <div className="space-y-4">
7      <Label>صدا</Label>
8      <Slider defaultValue={[50]} max={100} step={1} />
9    </div>
10  );
11}
12

با نمایش مقدار (With Value Display)

نمایش مقدار فعلی اسلایدر.

50%
مشاهده کد
1import { useState } from "react";
2import { Slider } from "@/components/ui/slider";
3import { Label } from "@/components/ui/label";
4import { Volume2 } from "lucide-react";
5
6export default function WithValueExample() {
7  const [volume, setVolume] = useState([50]);
8
9  return (
10    <div className="space-y-4">
11      <div className="flex items-center justify-between">
12        <Label htmlFor="volume">صدا</Label>
13        <span className="text-sm text-muted-foreground">{volume}%</span>
14      </div>
15      <div className="flex items-center gap-4">
16        <Volume2 className="h-4 w-4 text-muted-foreground" />
17        <Slider
18          id="volume"
19          value={volume}
20          onValueChange={setVolume}
21          max={100}
22          step={1}
23          className="flex-1"
24        />
25      </div>
26    </div>
27  );
28}
29

اسلایدر بازه‌ای (Range Slider)

انتخاب بازه مقدار با استفاده از دو دسته.

$20 - $80

تعداد دسته‌ها به صورت خودکار بر اساس طول آرایه مقدار تعیین می‌شود. برای اسلایدر بازه‌ای، آرایه با دو مقدار استفاده کنید

مشاهده کد
1import { useState } from "react";
2import { Slider } from "@/components/ui/slider";
3import { Label } from "@/components/ui/label";
4import { DollarSign } from "lucide-react";
5
6export default function RangeExample() {
7  const [priceRange, setPriceRange] = useState([20, 80]);
8
9  return (
10    <div className="space-y-4">
11      <div className="flex items-center justify-between">
12        <Label>محدوده قیمت</Label>
13        <span className="text-sm text-muted-foreground" dir="ltr">
14          ${priceRange[0]} - ${priceRange[1]}
15        </span>
16      </div>
17      <div className="flex items-center gap-4">
18        <DollarSign className="h-4 w-4 text-muted-foreground" />
19        <Slider
20          value={priceRange}
21          onValueChange={setPriceRange}
22          max={100}
23          step={1}
24          minStepsBetweenThumbs={1}
25          className="flex-1"
26        />
27      </div>
28      <p className="text-xs text-muted-foreground">
29        تعداد دسته‌ها به صورت خودکار بر اساس طول آرایه مقدار تعیین می‌شود. برای اسلایدر بازه‌ای، آرایه با دو مقدار استفاده کنید
30      </p>
31    </div>
32  );
33}
34

گام‌های مختلف (Different Steps)

تنظیم دقت انتخاب با استفاده از گام‌های مختلف.

مشاهده کد
1import { Slider } from "@/components/ui/slider";
2import { Label } from "@/components/ui/label";
3
4export default function StepsExample() {
5  return (
6    <div className="space-y-8">
7      {/* Step 1 */}
8      <div className="space-y-2">
9        <Label>دقیق (Step: 1)</Label>
10        <Slider defaultValue={[50]} max={100} step={1} />
11      </div>
12
13      {/* Step 5 */}
14      <div className="space-y-2">
15        <Label>متوسط (Step: 5)</Label>
16        <Slider defaultValue={[50]} max={100} step={5} />
17      </div>
18
19      {/* Step 10 */}
20      <div className="space-y-2">
21        <Label>درشت (Step: 10)</Label>
22        <Slider defaultValue={[50]} max={100} step={10} />
23      </div>
24    </div>
25  );
26}
27

مقادیر کمینه/بیشینه (Min/Max Values)

تنظیم محدوده تغییرات اسلایدر.

050
10200
مشاهده کد
1import { Slider } from "@/components/ui/slider";
2
3export default function MinMaxExample() {
4  return (
5    <div className="space-y-8">
6      {/* 0-50 */}
7      <div className="space-y-2">
8        <div className="flex justify-between text-sm text-muted-foreground">
9          <span>0</span>
10          <span>50</span>
11        </div>
12        <Slider defaultValue={[25]} min={0} max={50} step={1} />
13      </div>
14
15      {/* 10-200 */}
16      <div className="space-y-2">
17        <div className="flex justify-between text-sm text-muted-foreground">
18          <span>10</span>
19          <span>200</span>
20        </div>
21        <Slider defaultValue={[100]} min={10} max={200} step={5} />
22      </div>
23    </div>
24  );
25}
26

حالت غیرفعال (Disabled State)

اسلایدر غیرفعال که کاربر نمی‌تواند آن را تغییر دهد.

مشاهده کد
1import { Slider } from "@/components/ui/slider";
2import { Label } from "@/components/ui/label";
3
4export default function DisabledExample() {
5  return (
6    <div className="space-y-2">
7      <Label className="opacity-50">غیرفعال</Label>
8      <Slider defaultValue={[60]} max={100} disabled />
9    </div>
10  );
11}
12

مثال‌های پیشرفته (Advanced Examples)

موارد استفاده (Use Cases)

مثال‌های کاربردی مانند کنترل صدا، فیلتر قیمت و محدوده سنی.

75%

برای تنظیم سطح صدا از اسلایدر استفاده کنید

$20 - $80

محدوده قیمت محصولات را مشخص کنید

18-65 سال
0 سال100 سال
مشاهده کد
1import { useState } from "react";
2import { Slider } from "@/components/ui/slider";
3import { Label } from "@/components/ui/label";
4
5export default function UseCasesExample() {
6  const [brightness, setBrightness] = useState([75]);
7  const [priceRange, setPriceRange] = useState([20, 80]);
8
9  return (
10    <div className="space-y-8">
11      {/* Volume Control */}
12      <div className="space-y-4">
13        <div className="flex items-center justify-between">
14          <Label>سطح صدا</Label>
15          <span className="text-sm text-muted-foreground">
16            {brightness}%
17          </span>
18        </div>
19        <Slider
20          value={brightness}
21          onValueChange={setBrightness}
22          max={100}
23          step={1}
24        />
25        <p className="text-xs text-muted-foreground">
26          برای تنظیم سطح صدا از اسلایدر استفاده کنید
27        </p>
28      </div>
29
30      {/* Price Filter */}
31      <div className="space-y-4">
32        <div className="flex items-center justify-between">
33          <Label>محدوده قیمت</Label>
34          <span className="text-sm text-muted-foreground" dir="ltr">
35            ${priceRange[0]} - ${priceRange[1]}
36          </span>
37        </div>
38        <Slider
39          value={priceRange}
40          onValueChange={setPriceRange}
41          max={100}
42          step={1}
43          minStepsBetweenThumbs={5}
44        />
45        <p className="text-xs text-muted-foreground">
46          محدوده قیمت محصولات را مشخص کنید
47        </p>
48      </div>
49
50      {/* Age Range */}
51      <div className="space-y-4">
52        <div className="flex items-center justify-between">
53          <Label>سن</Label>
54          <span className="text-sm text-muted-foreground">
55            18-65 سال
56          </span>
57        </div>
58        <Slider
59          defaultValue={[18, 65]}
60          min={0}
61          max={100}
62          step={1}
63          minStepsBetweenThumbs={1}
64        />
65        <div className="flex justify-between text-xs text-muted-foreground">
66          <span>0 سال</span>
67          <span>100 سال</span>
68        </div>
69      </div>
70    </div>
71  );
72}
73

مرجع API (API Reference)

Slider

پراپ‌های کامپوننت Slider.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
valuenumber[]undefinedمقدار کنترل شده
defaultValuenumber[][0]مقدار پیش‌فرض (غیرکنترل شده)
onValueChange(value: number[]) => voidundefinedتابع فراخوانی هنگام تغییر مقدار
onValueCommit(value: number[]) => voidundefinedتابع فراخوانی هنگام اتمام تغییر (رها کردن)
minnumber0حداقل مقدار
maxnumber100حداکثر مقدار
stepnumber1اندازه هر گام
minStepsBetweenThumbsnumber0حداقل فاصله بین دسته‌ها
orientation"horizontal" | "vertical""horizontal"جهت اسلایدر
disabledbooleanfalseغیرفعال کردن اسلایدر
classNamestring-کلاس‌های CSS سفارشی

دسترسی‌پذیری (Accessibility)

کیبورد (Keyboard)

  • Arrow Keys - افزایش/کاهش به اندازه step
  • Shift + Arrow - تغییرات بزرگتر
  • Page Up/Down - پرش‌های بزرگ
  • Home - رفتن به حداقل
  • End - رفتن به حداکثر

ARIA برچسب‌ها (ARIA Labels)

از aria-label برای توضیح هدف اسلایدر استفاده کنید

ورودی‌های مخفی (Hidden Inputs)

اسلایدر به صورت خودکار ورودی‌های مخفی برای ارسال فرم ایجاد می‌کند

بهترین شیوه‌ها (Best Practices)

نمایش مقدار (Show Value)

همیشه مقدار فعلی را نمایش دهید تا کاربر بداند چه عددی را انتخاب کرده است

گام مناسب (Appropriate Step)

اندازه گام را بر اساس دقت مورد نیاز تنظیم کنید. برای تنظیمات دقیق از step کوچک استفاده کنید

برچسب‌گذاری (Labeling)

برای اسلایدر برچسب واضح و مقادیر min/max قرار دهید تا کاربر بازه را بداند

استفاده از بازه (Using Range)

برای فیلترها (مثل قیمت، سن) از اسلایدر بازه‌ای با دو دسته استفاده کنید

بازخورد بصری (Visual Feedback)

تغییرات را به صورت آنی نشان دهید تا کاربر نتیجه را ببیند