فیلد فرم (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 با جهت افقی.
مشاهده کد
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) |
|---|---|---|---|
className | string | - | کلاسهای CSS سفارشی |
FieldLegend
عنوان برای FieldSet.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
variant | "legend" | "label" | "legend" | نوع ظاهری. نوع label اندازه برچسب را اعمال میکند. |
className | string | - | کلاسهای CSS سفارشی |
Field
پوششدهنده اصلی برای یک فیلد منفرد.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
orientation | "vertical" | "horizontal" | "responsive" | "vertical" | جهت چیدمان فیلد |
data-invalid | boolean | - | فعالسازی حالت خطا |
className | string | - | کلاسهای CSS سفارشی |
FieldError
محفظه خطای دسترسیپذیر.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
errors | Array<{ message?: string }> | - | آرایه خطاها (مثلاً از react-hook-form) |
className | string | - | کلاسهای CSS سفارشی |
FieldDescription
توضیحات کمکی برای فیلد.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
className | string | - | کلاسهای CSS سفارشی |
FieldSeparator
جداکننده بصری برای تفکیک بخشها در یک FieldGroup.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
children | ReactNode | - | متن اختیاری بین خطوط جداکننده |
پشتیبانی RTL
کامپوننت فیلد به طور کامل از جهتگیری راستچین پشتیبانی میکند. برچسبها، توضیحات و پیامهای خطا به صورت خودکار بر اساس جهت سند تنظیم میشوند.
- در حالت
horizontalبرچسب و کنترل در کنار هم قرار میگیرند FieldSetوFieldLegendگروهبندی معنایی برای دسترسیپذیری فراهم میکنندFieldErrorازrole="alert"برای فنآوریهای کمکی استفاده میکند
دسترسیپذیری (Accessibility)
FieldSet و FieldLegend گروهبندی معنایی برای کاربران صفحهکلید و فنآوریهای کمکی فراهم میکنند.
Field با role="group" خروجی میدهد تا کنترلهای تودرتو برچسبگذاری را از FieldLabel به ارث ببرند.
از FieldSeparator با احتیاط استفاده کنید تا صفحهخوانها با مرزهای بخش روشن مواجه شوند.