گروه دکمه‌ها (Button Group)

کانتینری برای گروه‌بندی دکمه‌های مرتبط با استایل و فاصله‌گذاری یکسان، با پشتیبانی کامل از RTL.

نصب (Installation)

1npx @quark-lab/rad-ui add button-group

نمونه‌ها (Examples)

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

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

مشاهده کد
1import { Button, ButtonGroup } from "@/components/ui/button-group";
2
3export default function BasicExample() {
4  return (
5    <ButtonGroup>
6      <Button>دکمه ۱</Button>
7      <Button>دکمه ۲</Button>
8    </ButtonGroup>
9  );
10}
11

جهت چیدمان (Orientation)

تغییر جهت گروه بین حالت افقی و عمودی.

مشاهده کد
1import { Button, ButtonGroup } from "@/components/ui/button-group";
2
3export default function OrientationExample() {
4  return (
5    <div className="flex flex-col gap-4">
6      <ButtonGroup orientation="horizontal">
7        <Button>چپ</Button>
8        <Button>وسط</Button>
9        <Button>راست</Button>
10      </ButtonGroup>
11
12      <ButtonGroup orientation="vertical">
13        <Button>بالا</Button>
14        <Button>وسط</Button>
15        <Button>پایین</Button>
16      </ButtonGroup>
17    </div>
18  );
19}
20

جداکننده (Separator)

افزودن جداکننده بصری بین دکمه‌ها برای تفکیک عملیات.

مشاهده کد
1import {
2  Button,
3  ButtonGroup,
4  ButtonGroupSeparator,
5} from "@/components/ui/button-group";
6
7export default function SeparatorExample() {
8  return (
9    <ButtonGroup>
10      <Button variant="outline">آرشیو</Button>
11      <ButtonGroupSeparator />
12      <Button variant="outline">حذف</Button>
13    </ButtonGroup>
14  );
15}
16

دکمه دو بخشی (Split Button)

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

مشاهده کد
1import { ChevronDown } from "lucide-react";
2import {
3  Button,
4  ButtonGroup,
5  ButtonGroupSeparator,
6} from "@/components/ui/button-group";
7
8export default function SplitExample() {
9  return (
10    <ButtonGroup>
11      <Button>اقدام اصلی</Button>
12      <ButtonGroupSeparator />
13      <Button variant="outline" aria-label="گزینه‌های بیشتر">
14        <ChevronDown className="w-4 h-4" />
15      </Button>
16    </ButtonGroup>
17  );
18}
19

گروه همراه با ورودی (With Input)

گروه‌بندی دکمه‌ها همراه با فیلد ورودی برای اکشن‌های مرتبط.

مشاهده کد
1import { Button, ButtonGroup, Input } from "@/components/ui/button-group";
2
3export default function InputExample() {
4  return (
5    <ButtonGroup>
6      <Button variant="outline">جستجو</Button>
7      <Input placeholder="عبارت مورد نظر را وارد کنید..." className="max-w-xs" />
8    </ButtonGroup>
9  );
10}
11

مرجع API (API Reference)

ButtonGroup

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

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
orientation"horizontal" | "vertical""horizontal"جهت چیدمان دکمه‌ها در گروه
classNamestring-کلاس‌های CSS سفارشی برای ریشه گروه

ButtonGroupSeparator

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

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

ButtonGroupText

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

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

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

نقش گروه (Group Role)

کامپوننت ButtonGroup به صورت پیش‌فرض از role="group" استفاده می‌کند تا مجموعه‌ای از دکمه‌های مرتبط را به خوانندگان صفحه معرفی کند.

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

برای توصیف هدف گروه از aria-label یا aria-labelledby استفاده کنید تا کاربران با فناوری‌های کمکی بهتر متوجه هدف گروه شوند.

جهت RTL (RTL Direction)

چیدمان دکمه‌ها و فاصله‌گذاری آن‌ها با در نظر گرفتن dir="rtl" طراحی شده و در هر دو حالت جهت افقی و عمودی به درستی کار می‌کند.

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

گروه‌بندی عملیات مرتبط (Group Related Actions)

از ButtonGroup برای قرار دادن عملیات مرتبط در کنار هم استفاده کنید؛ مثل دکمه‌های مربوط به وضعیت محتوا، فیلترها یا دسته‌ای از اکشن‌های ثانویه.

استفاده از جداکننده (Separators)

زمانی که در یک گروه چند دسته عملیات دارید، از ButtonGroupSeparator برای تفکیک بصری استفاده کنید.

برچسب‌گذاری واضح (Clear Labelling)

از ButtonGroupText یا یک برچسب مجزا برای توضیح هدف گروه استفاده کنید، مخصوصاً در فرم‌ها و نوار ابزارها.

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

1import {
2  Button,
3  ButtonGroup,
4  ButtonGroupSeparator,
5  ButtonGroupText,
6} from "@/components/ui/button-group";
7
8export default function ButtonGroupUsage() {
9  return (
10    <ButtonGroup aria-label="گروه دکمه‌های عملیات">
11      <ButtonGroupText>وضعیت</ButtonGroupText>
12      <Button variant="outline">پیش‌نویس</Button>
13      <Button variant="outline">منتشر شده</Button>
14      <ButtonGroupSeparator />
15      <Button>ذخیره</Button>
16    </ButtonGroup>
17  );
18}
19