کالپس (Collapsible)

کامپوننت تعاملی برای باز و بسته کردن بخش‌های محتوا؛ مناسب برای جزئیات اضافی، تنظیمات پیشرفته و ساخت درخت فایل. کاملاً سازگار با RTL و قابل ترکیب با سایر کامپوننت‌های Rad UI.

نصب (Installation)

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

نمونه‌ها (Examples)

نمونه پایه (Basic)

کالپس ساده برای نمایش جزئیات بیشتر یک کارت محصول.

مشاهده کد
1import { Button, Card, CardContent } from "@/components/ui/card";
2import {
3  Collapsible,
4  CollapsibleContent,
5  CollapsibleTrigger,
6} from "@/components/ui/collapsible";
7
8export default function BasicCollapsibleExample() {
9  return (
10    <Card className="mx-auto w-full max-w-sm">
11      <CardContent className="p-2">
12        <Collapsible className="w-full rounded-md border border-border data-[state=open]:bg-muted">
13          <CollapsibleTrigger className="group flex w-full items-center justify-between px-3 py-2 text-sm font-medium">
14            جزئیات محصول
15            <span className="ms-auto text-xs text-muted-foreground group-data-[state=open]:rotate-180">
1617            </span>
18          </CollapsibleTrigger>
19          <CollapsibleContent className="flex flex-col items-start gap-2 border-t border-border px-3 pb-3 pt-2 text-sm text-muted-foreground data-[state=closed]:border-t-0 data-[state=closed]:p-0">
20            <div>
21              این بخش می‌تواند برای نمایش توضیحات تکمیلی محصول باز و بسته شود.
22            </div>
23            <Button size="sm">بیشتر بدانید</Button>
24          </CollapsibleContent>
25        </Collapsible>
26      </CardContent>
27    </Card>
28  );
29}
30

حالت کنترل‌شده (Controlled State)

مدیریت وضعیت باز/بسته توسط state خارجی با onOpenChange.

مشاهده کد
1import * as React from "react";
2
3import {
4  Button,
5  Collapsible,
6  CollapsibleContent,
7  CollapsibleTrigger,
8} from "@/components/ui/collapsible";
9
10export default function ControlledCollapsibleExample() {
11  const [open, setOpen] = React.useState(false);
12
13  return (
14    <div className="flex w-full max-w-sm flex-col items-stretch gap-3">
15      <Button
16        variant="outline"
17        className="w-full"
18        onClick={() => setOpen((prev) => !prev)}
19      >
20        {open ? "بستن جزئیات" : "نمایش جزئیات"}
21      </Button>
22
23      <Collapsible
24        open={open}
25        onOpenChange={setOpen}
26        className="space-y-2 w-full"
27      >
28        <CollapsibleTrigger className="text-sm font-medium text-primary underline-offset-4 hover:underline">
29          تغییر وضعیت از داخل کامپوننت
30        </CollapsibleTrigger>
31        <CollapsibleContent className="text-sm text-muted-foreground">
32          این نمونه نشان می‌دهد چگونه می‌توانید وضعیت باز/بسته را به صورت
33          کنترل‌شده مدیریت کنید.
34        </CollapsibleContent>
35      </Collapsible>
36    </div>
37  );
38}
39

پنل تنظیمات (Settings Panel)

استفاده از Collapsible برای نمایش تنظیمات پیشرفته در فرم.

شعاع گوشه‌ها

شعاع گوشه‌های المان را تنظیم کنید.

مشاهده کد
1import * as React from "react";
2import {
3  Button,
4  Card,
5  CardContent,
6  CardDescription,
7  CardHeader,
8  CardTitle,
9  Collapsible,
10  CollapsibleContent,
11  CollapsibleTrigger,
12  Field,
13  FieldGroup,
14  FieldLabel,
15  Input,
16} from "@/components/ui/collapsible";
17import { Maximize, Minimize } from "lucide-react";
18
19export default function CollapsibleSettingsPanel() {
20  const [open, setOpen] = React.useState(false);
21
22  return (
23    <Card className="mx-auto w-full max-w-xs" size="sm">
24      <CardHeader>
25        <CardTitle>شعاع گوشه‌ها</CardTitle>
26        <CardDescription>شعاع گوشه‌های المان را تنظیم کنید.</CardDescription>
27      </CardHeader>
28      <CardContent>
29        <Collapsible
30          open={open}
31          onOpenChange={setOpen}
32          className="flex items-start gap-2"
33        >
34          <FieldGroup className="grid w-full grid-cols-2 gap-2">
35            <Field>
36              <FieldLabel htmlFor="radius-x" className="sr-only">
37                Radius X
38              </FieldLabel>
39              <Input id="radius-x" placeholder="0" defaultValue={0} />
40            </Field>
41            <Field>
42              <FieldLabel htmlFor="radius-y" className="sr-only">
43                Radius Y
44              </FieldLabel>
45              <Input id="radius-y" placeholder="0" defaultValue={0} />
46            </Field>
47            <CollapsibleContent className="col-span-full grid grid-cols-subgrid gap-2">
48              <Field>
49                <FieldLabel htmlFor="radius-top" className="sr-only">
50                  Radius Top
51                </FieldLabel>
52                <Input id="radius-top" placeholder="0" defaultValue={0} />
53              </Field>
54              <Field>
55                <FieldLabel htmlFor="radius-bottom" className="sr-only">
56                  Radius Bottom
57                </FieldLabel>
58                <Input id="radius-bottom" placeholder="0" defaultValue={0} />
59              </Field>
60            </CollapsibleContent>
61          </FieldGroup>
62          <CollapsibleTrigger asChild>
63            <Button
64              variant="outline"
65              size="sm"
66              className="aspect-square p-0"
67              aria-label={open ? "بستن تنظیمات پیشرفته" : "نمایش تنظیمات پیشرفته"}
68            >
69              {open ? (
70                <Minimize className="w-4 h-4" />
71              ) : (
72                <Maximize className="w-4 h-4" />
73              )}
74            </Button>
75          </CollapsibleTrigger>
76        </Collapsible>
77      </CardContent>
78    </Card>
79  );
80}
81

مرجع API (API Reference)

Collapsible

کامپوننت ریشه که وضعیت باز/بسته را مدیریت می‌کند.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
openbooleanundefinedوضعیت باز/بسته به صورت کنترل‌شده. در صورت استفاده باید همراه با onOpenChange باشد.
defaultOpenbooleanfalseباز بودن اولیه کامپوننت در حالت غیرکنترل‌شده.
onOpenChange(open: boolean) => voidundefinedتابع فراخوانی هنگام تغییر وضعیت باز/بسته.
disabledbooleanfalseغیرفعال کردن تعامل با کامپوننت.
classNamestring-کلاس‌های CSS سفارشی برای ریشه Collapsible.

CollapsibleTrigger

تریگری که با کلیک روی آن محتوا باز یا بسته می‌شود.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
asChildbooleanfalseدر صورت true شدن، به جای دکمه پیش‌فرض، کامپوننت فرزند به عنوان ریشه رندر می‌شود.
classNamestring-کلاس‌های CSS سفارشی برای تریگر.

CollapsibleContent

محتوای جمع‌شونده که زیر تریگر نمایش داده می‌شود.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
classNamestring-کلاس‌های CSS سفارشی برای محتوای جمع‌شونده (روی روت محتوا اعمال می‌شود).

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

نقش و وضعیت (Role & State)

کالپس بر پایه Radix Collapsible ساخته شده و به صورت خودکار نقش‌ها و وضعیت data-state="open" | "closed" را مدیریت می‌کند.

کیبورد (Keyboard)

  • Enter و Space — باز یا بسته کردن کالپس در هنگام فوکوس روی تریگر.
  • Tab — حرکت بین تریگر و سایر المان‌های قابل فوکوس.

پشتیبانی RTL

از کلاس‌هایی مثل ms-auto و text-start استفاده کنید تا چیدمان در جهت راست‌به‌چپ و چپ‌به‌راست درست عمل کند.

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

چه زمانی از Collapsible استفاده کنیم؟

  • نمایش جزئیات سفارش، محصول یا رکورد دیتابیس.
  • تنظیمات پیشرفته که همیشه لازم نیست دیده شوند.
  • درخت فایل یا ساختار‌های سلسله‌مراتبی کوچک.

برچسب‌گذاری واضح

متن تریگر را واضح و توصیفی انتخاب کنید تا کاربر بداند با باز کردن چه محتوایی نمایش داده می‌شود.

ترکیب با سایر کامپوننت‌ها

Collapsible را می‌توانید با کامپوننت‌هایی مثل Card، Field، Input و Tabs ترکیب کنید تا الگوهای UI غنی‌تری بسازید.

نحوه استفاده (Usage)

1import {
2  Collapsible,
3  CollapsibleContent,
4  CollapsibleTrigger,
5} from "@/components/ui/collapsible";
6
7export default function CollapsibleUsage() {
8  return (
9    <Collapsible className="space-y-2">
10      <CollapsibleTrigger className="text-sm font-medium underline-offset-4 hover:underline">
11        آیا می‌توانم از این کامپوننت در پروژه استفاده کنم؟
12      </CollapsibleTrigger>
13      <CollapsibleContent className="text-sm text-muted-foreground">
14        بله. استفاده شخصی و تجاری آزاد است و نیازی به ذکر منبع نیست.
15      </CollapsibleContent>
16    </Collapsible>
17  );
18}
19