فیلد فرم (Field)

ترکیب برچسب‌ها، کنترل‌ها و متن‌های راهنما برای ساخت فیلدهای فرم دسترسی‌پذیر و گروه‌بندی ورودی‌ها.

نصب (Installation)

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

نمونه‌ها (Examples)

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

ساده‌ترین حالت استفاده از فیلد با برچسب و توضیحات.

این نام در پروفایل شما نمایش داده می‌شود.

مشاهده کد
1import {
2  Field,
3  FieldLabel,
4  FieldDescription,
5} from "@/components/ui/field";
6import { Input } from "@/components/ui/input";
7
8export default function BasicExample() {
9  return (
10    <div className="max-w-sm">
11      <Field>
12        <FieldLabel htmlFor="basic-name">نام کامل</FieldLabel>
13        <Input id="basic-name" placeholder="نام خود را وارد کنید" />
14        <FieldDescription>
15          این نام در پروفایل شما نمایش داده می‌شود.
16        </FieldDescription>
17      </Field>
18    </div>
19  );
20}
21

ورودی (Input)

استفاده از Input داخل Field.

نام کاربری یکتا برای حساب شما.

حداقل ۸ کاراکتر باید داشته باشد.

مشاهده کد
1import {
2  Field,
3  FieldLabel,
4  FieldDescription,
5} from "@/components/ui/field";
6import { Input } from "@/components/ui/input";
7
8export default function InputExample() {
9  return (
10    <div className="max-w-sm space-y-6">
11      <Field>
12        <FieldLabel htmlFor="field-username">نام کاربری</FieldLabel>
13        <Input
14          id="field-username"
15          placeholder="یک نام کاربری انتخاب کنید"
16        />
17        <FieldDescription>
18          نام کاربری یکتا برای حساب شما.
19        </FieldDescription>
20      </Field>
21      <Field>
22        <FieldLabel htmlFor="field-password">رمز عبور</FieldLabel>
23        <Input
24          id="field-password"
25          type="password"
26          placeholder="رمز عبور"
27        />
28        <FieldDescription>
29          حداقل ۸ کاراکتر باید داشته باشد.
30        </FieldDescription>
31      </Field>
32    </div>
33  );
34}
35

ناحیه متن (Textarea)

استفاده از Textarea داخل Field.

نظرات خود درباره خدمات ما را با ما به اشتراک بگذارید.

مشاهده کد
1import {
2  Field,
3  FieldLabel,
4  FieldDescription,
5} from "@/components/ui/field";
6import { Textarea } from "@/components/ui/textarea";
7
8export default function TextareaExample() {
9  return (
10    <div className="max-w-sm">
11      <Field>
12        <FieldLabel htmlFor="field-feedback">بازخورد</FieldLabel>
13        <Textarea
14          id="field-feedback"
15          placeholder="نظر خود را بنویسید..."
16          rows={4}
17        />
18        <FieldDescription>
19          نظرات خود درباره خدمات ما را با ما به اشتراک بگذارید.
20        </FieldDescription>
21      </Field>
22    </div>
23  );
24}
25

اسلایدر (Slider)

استفاده از Slider داخل Field.

بودجه خود را تنظیم کنید (400 تومان).

مشاهده کد
1import { useState } from "react";
2import {
3  Field,
4  FieldLabel,
5  FieldDescription,
6} from "@/components/ui/field";
7import { Slider } from "@/components/ui/slider";
8
9export default function SliderExample() {
10  const [sliderValue, setSliderValue] = useState([400]);
11
12  return (
13    <div className="max-w-sm">
14      <Field>
15        <FieldLabel>محدوده قیمت</FieldLabel>
16        <Slider
17          value={sliderValue}
18          onValueChange={setSliderValue}
19          min={0}
20          max={1000}
21          step={50}
22        />
23        <FieldDescription>
24          بودجه خود را تنظیم کنید ({sliderValue[0]} تومان).
25        </FieldDescription>
26      </Field>
27    </div>
28  );
29}
30

مجموعه فیلد (FieldSet)

گروه‌بندی فیلدها با FieldSet و FieldLegend.

اطلاعات آدرس

آدرس شما برای ارسال سفارش مورد نیاز است.

مشاهده کد
1import {
2  Field,
3  FieldLabel,
4  FieldDescription,
5  FieldSet,
6  FieldLegend,
7  FieldGroup,
8} from "@/components/ui/field";
9import { Input } from "@/components/ui/input";
10
11export default function FieldSetExample() {
12  return (
13    <div className="max-w-md">
14      <FieldSet>
15        <FieldLegend>اطلاعات آدرس</FieldLegend>
16        <FieldDescription>
17          آدرس شما برای ارسال سفارش مورد نیاز است.
18        </FieldDescription>
19        <FieldGroup>
20          <Field>
21            <FieldLabel htmlFor="fs-street">آدرس خیابان</FieldLabel>
22            <Input id="fs-street" placeholder="خیابان و کوچه" />
23          </Field>
24          <Field>
25            <FieldLabel htmlFor="fs-city">شهر</FieldLabel>
26            <Input id="fs-city" placeholder="شهر" />
27          </Field>
28          <Field>
29            <FieldLabel htmlFor="fs-postal">کد پستی</FieldLabel>
30            <Input id="fs-postal" placeholder="کد پستی ۱۰ رقمی" />
31          </Field>
32        </FieldGroup>
33      </FieldSet>
34    </div>
35  );
36}
37

چک‌باکس (Checkbox)

استفاده از Checkbox در Field با جهت افقی.

موارد نمایشی

موارد مورد نظر برای نمایش در دسکتاپ را انتخاب کنید.

پوشه‌های دسکتاپ و اسناد شما با iCloud Drive همگام‌سازی می‌شوند.

مشاهده کد
1import {
2  Field,
3  FieldLabel,
4  FieldDescription,
5  FieldSet,
6  FieldLegend,
7  FieldGroup,
8  FieldSeparator,
9  FieldContent,
10} from "@/components/ui/field";
11import { Checkbox } from "@/components/ui/checkbox";
12
13export default function CheckboxExample() {
14  return (
15    <div className="max-w-md">
16      <FieldSet>
17        <FieldLegend>موارد نمایشی</FieldLegend>
18        <FieldDescription>
19          موارد مورد نظر برای نمایش در دسکتاپ را انتخاب کنید.
20        </FieldDescription>
21        <FieldGroup>
22          <Field orientation="horizontal">
23            <Checkbox id="check-hdd" />
24            <FieldLabel htmlFor="check-hdd">دیسک‌های سخت</FieldLabel>
25          </Field>
26          <Field orientation="horizontal">
27            <Checkbox id="check-ext" />
28            <FieldLabel htmlFor="check-ext">دیسک‌های خارجی</FieldLabel>
29          </Field>
30          <Field orientation="horizontal">
31            <Checkbox id="check-cd" />
32            <FieldLabel htmlFor="check-cd">CD، DVD و iPod</FieldLabel>
33          </Field>
34          <FieldSeparator />
35          <Field orientation="horizontal">
36            <Checkbox id="check-sync" />
37            <FieldContent>
38              <FieldLabel htmlFor="check-sync">
39                همگام‌سازی دسکتاپ و اسناد
40              </FieldLabel>
41              <FieldDescription>
42                پوشه‌های دسکتاپ و اسناد شما با iCloud Drive همگام‌سازی می‌شوند.
43              </FieldDescription>
44            </FieldContent>
45          </Field>
46        </FieldGroup>
47      </FieldSet>
48    </div>
49  );
50}
51

دکمه رادیویی (Radio)

استفاده از RadioGroup در FieldSet.

طرح اشتراک

طرح‌های سالانه و مادام‌العمر تخفیف قابل توجهی دارند.

مشاهده کد
1import {
2  Field,
3  FieldLabel,
4  FieldDescription,
5  FieldSet,
6  FieldLegend,
7  FieldGroup,
8} from "@/components/ui/field";
9import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
10
11export default function RadioExample() {
12  return (
13    <div className="max-w-md">
14      <FieldSet>
15        <FieldLegend>طرح اشتراک</FieldLegend>
16        <FieldDescription>
17          طرح‌های سالانه و مادام‌العمر تخفیف قابل توجهی دارند.
18        </FieldDescription>
19        <RadioGroup defaultValue="monthly">
20          <FieldGroup>
21            <Field orientation="horizontal">
22              <RadioGroupItem value="monthly" id="radio-monthly" />
23              <FieldLabel htmlFor="radio-monthly">
24                ماهانه (۹۹,۰۰۰ تومان/ماه)
25              </FieldLabel>
26            </Field>
27            <Field orientation="horizontal">
28              <RadioGroupItem value="yearly" id="radio-yearly" />
29              <FieldLabel htmlFor="radio-yearly">
30                سالانه (۹۹۰,۰۰۰ تومان/سال)
31              </FieldLabel>
32            </Field>
33            <Field orientation="horizontal">
34              <RadioGroupItem value="lifetime" id="radio-lifetime" />
35              <FieldLabel htmlFor="radio-lifetime">
36                مادام‌العمر (۲,۹۹۰,۰۰۰ تومان)
37              </FieldLabel>
38            </Field>
39          </FieldGroup>
40        </RadioGroup>
41      </FieldSet>
42    </div>
43  );
44}
45

سوئیچ (Switch)

استفاده از Switch در Field با جهت افقی.

مشاهده کد
1import { Field, FieldLabel } from "@/components/ui/field";
2import { Switch } from "@/components/ui/switch";
3
4export default function SwitchExample() {
5  return (
6    <div className="max-w-sm">
7      <Field orientation="horizontal">
8        <Switch id="switch-mfa" />
9        <FieldLabel htmlFor="switch-mfa">
10          احراز هویت دو مرحله‌ای
11        </FieldLabel>
12      </Field>
13    </div>
14  );
15}
16

گروه فیلد (Field Group)

گروه‌بندی فیلدها با FieldGroup و جداکننده.

اعلان‌ها

هنگام پاسخ به درخواست‌ها اطلاع‌رسانی دریافت کنید.

دریافت اعلان در دستگاه شما.

دریافت اعلان از طریق ایمیل.

دریافت پیامک برای رویدادهای مهم.

مشاهده کد
1import {
2  Field,
3  FieldLabel,
4  FieldDescription,
5  FieldSet,
6  FieldLegend,
7  FieldGroup,
8  FieldSeparator,
9  FieldContent,
10} from "@/components/ui/field";
11import { Checkbox } from "@/components/ui/checkbox";
12
13export default function FieldGroupExample() {
14  return (
15    <div className="max-w-md">
16      <FieldSet>
17        <FieldLegend>اعلان‌ها</FieldLegend>
18        <FieldDescription>
19          هنگام پاسخ به درخواست‌ها اطلاع‌رسانی دریافت کنید.
20        </FieldDescription>
21        <FieldGroup>
22          <Field orientation="horizontal">
23            <Checkbox id="fg-push" defaultChecked />
24            <FieldContent>
25              <FieldLabel htmlFor="fg-push">اعلان‌های فوری</FieldLabel>
26              <FieldDescription>
27                دریافت اعلان در دستگاه شما.
28              </FieldDescription>
29            </FieldContent>
30          </Field>
31          <FieldSeparator />
32          <Field orientation="horizontal">
33            <Checkbox id="fg-email" />
34            <FieldContent>
35              <FieldLabel htmlFor="fg-email">اعلان ایمیلی</FieldLabel>
36              <FieldDescription>
37                دریافت اعلان از طریق ایمیل.
38              </FieldDescription>
39            </FieldContent>
40          </Field>
41          <Field orientation="horizontal">
42            <Checkbox id="fg-sms" />
43            <FieldContent>
44              <FieldLabel htmlFor="fg-sms">اعلان پیامکی</FieldLabel>
45              <FieldDescription>
46                دریافت پیامک برای رویدادهای مهم.
47              </FieldDescription>
48            </FieldContent>
49          </Field>
50        </FieldGroup>
51      </FieldSet>
52    </div>
53  );
54}
55

اعتبارسنجی (Validation)

نمایش پیام‌های خطا با FieldError.

مشاهده کد
1import {
2  Field,
3  FieldLabel,
4  FieldError,
5} from "@/components/ui/field";
6import { Input } from "@/components/ui/input";
7
8export default function ValidationExample() {
9  return (
10    <div className="max-w-sm space-y-6">
11      <Field data-invalid="true">
12        <FieldLabel htmlFor="err-email">ایمیل</FieldLabel>
13        <Input
14          id="err-email"
15          type="email"
16          aria-invalid
17          defaultValue="invalid-email"
18          className="border-destructive focus-visible:ring-destructive"
19        />
20        <FieldError>یک آدرس ایمیل معتبر وارد کنید.</FieldError>
21      </Field>
22      <Field data-invalid="true">
23        <FieldLabel htmlFor="err-username">نام کاربری</FieldLabel>
24        <Input
25          id="err-username"
26          aria-invalid
27          defaultValue="admin"
28          className="border-destructive focus-visible:ring-destructive"
29        />
30        <FieldError>
31          این نام کاربری قبلاً استفاده شده است. نام دیگری انتخاب کنید.
32        </FieldError>
33      </Field>
34    </div>
35  );
36}
37

مثال عملی (Practical Example)

فرم پرداخت (Payment Form)

یک فرم پرداخت کامل با استفاده از تمام اجزای Field.

اطلاعات پرداخت

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

شماره کارت ۱۶ رقمی خود را وارد کنید.

آدرس صورتحساب مرتبط با روش پرداخت شما.

مشاهده کد
1import {
2  Field,
3  FieldLabel,
4  FieldDescription,
5  FieldSet,
6  FieldLegend,
7  FieldGroup,
8  FieldSeparator,
9} from "@/components/ui/field";
10import { Input } from "@/components/ui/input";
11import { Checkbox } from "@/components/ui/checkbox";
12import { Textarea } from "@/components/ui/textarea";
13import { Button } from "@/components/ui/button";
14
15export default function PaymentFormExample() {
16  return (
17    <div className="max-w-lg">
18      <FieldSet>
19        <FieldLegend>اطلاعات پرداخت</FieldLegend>
20        <FieldDescription>
21          تمام تراکنش‌ها امن و رمزنگاری شده هستند.
22        </FieldDescription>
23        <FieldGroup>
24          <Field>
25            <FieldLabel htmlFor="pay-name">نام روی کارت</FieldLabel>
26            <Input id="pay-name" placeholder="نام کامل" />
27          </Field>
28          <Field>
29            <FieldLabel htmlFor="pay-card">شماره کارت</FieldLabel>
30            <Input
31              id="pay-card"
32              placeholder="شماره کارت ۱۶ رقمی"
33              dir="ltr"
34            />
35            <FieldDescription>
36              شماره کارت ۱۶ رقمی خود را وارد کنید.
37            </FieldDescription>
38          </Field>
39          <div className="grid grid-cols-1 sm:grid-cols-3 gap-4">
40            <Field>
41              <FieldLabel htmlFor="pay-month">ماه</FieldLabel>
42              <Input id="pay-month" placeholder="MM" dir="ltr" />
43            </Field>
44            <Field>
45              <FieldLabel htmlFor="pay-year">سال</FieldLabel>
46              <Input id="pay-year" placeholder="YYYY" dir="ltr" />
47            </Field>
48            <Field>
49              <FieldLabel htmlFor="pay-cvv">CVV</FieldLabel>
50              <Input id="pay-cvv" placeholder="CVV" dir="ltr" />
51            </Field>
52          </div>
53          <FieldSeparator />
54          <Field>
55            <FieldLabel htmlFor="pay-address">آدرس صورتحساب</FieldLabel>
56            <Input id="pay-address" placeholder="آدرس" />
57            <FieldDescription>
58              آدرس صورتحساب مرتبط با روش پرداخت شما.
59            </FieldDescription>
60          </Field>
61          <Field orientation="horizontal">
62            <Checkbox id="pay-same" />
63            <FieldLabel htmlFor="pay-same">
64              آدرس صورتحساب همان آدرس ارسال است
65            </FieldLabel>
66          </Field>
67          <Field>
68            <FieldLabel htmlFor="pay-comments">توضیحات</FieldLabel>
69            <Textarea
70              id="pay-comments"
71              placeholder="توضیحات اختیاری..."
72              rows={3}
73            />
74          </Field>
75        </FieldGroup>
76      </FieldSet>
77      <div className="flex justify-end gap-3 mt-6">
78        <Button variant="outline" type="button">
79          لغو
80        </Button>
81        <Button type="submit">ثبت</Button>
82      </div>
83    </div>
84  );
85}
86

مرجع API (API Reference)

FieldSet

محفظه‌ای که یک fieldset معنایی با فاصله‌گذاری پیش‌فرض رندر می‌کند.

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

FieldLegend

عنوان برای FieldSet.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
variant"legend" | "label""legend"نوع ظاهری. نوع label اندازه برچسب را اعمال می‌کند.
classNamestring-کلاس‌های CSS سفارشی

Field

پوشش‌دهنده اصلی برای یک فیلد منفرد.

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

FieldError

محفظه خطای دسترسی‌پذیر.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
errorsArray<{ message?: string }>-آرایه خطاها (مثلاً از react-hook-form)
classNamestring-کلاس‌های CSS سفارشی

FieldDescription

توضیحات کمکی برای فیلد.

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

FieldSeparator

جداکننده بصری برای تفکیک بخش‌ها در یک FieldGroup.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
childrenReactNode-متن اختیاری بین خطوط جداکننده

پشتیبانی RTL

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

  • در حالت horizontal برچسب و کنترل در کنار هم قرار می‌گیرند
  • FieldSet و FieldLegend گروه‌بندی معنایی برای دسترسی‌پذیری فراهم می‌کنند
  • FieldError از role="alert" برای فن‌آوری‌های کمکی استفاده می‌کند

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

FieldSet و FieldLegend گروه‌بندی معنایی برای کاربران صفحه‌کلید و فن‌آوری‌های کمکی فراهم می‌کنند.

Field با role="group" خروجی می‌دهد تا کنترل‌های تودرتو برچسب‌گذاری را از FieldLabel به ارث ببرند.

از FieldSeparator با احتیاط استفاده کنید تا صفحه‌خوان‌ها با مرزهای بخش روشن مواجه شوند.