کامپوننتها
ورودی
فیلد متن تکخطی و چندخطی، با برچسب، متن راهنما، پیام خطا و افزونه.
import { Input, Textarea } from "@kashi-ui/react";
پایه
برچسب، متن راهنما و فیلد بهصورت خودکار با id و aria-describedby به هم وصل میشوند.
همانطور که در کارت ملی آمده است.
<Input label="نام و نام خانوادگی" placeholder="مثلاً سارا احمدی" hint="همانطور که در کارت ملی آمده است." required /><div class="k-field">
<div class="k-field__label-row">
<label class="k-label" for=":r3R0:">نام و نام خانوادگی<span class="k-label__required" aria-hidden="true">*</span></label>
</div>
<div class="k-input" data-size="md">
<input id=":r3R0:" class="k-input__control" type="text" required="" aria-describedby=":r3R0:-hint" placeholder="مثلاً سارا احمدی"/>
</div>
<div class="k-field__hint-row">
<div class="k-field__hints">
<p class="k-hint" id=":r3R0:-hint">همانطور که در کارت ملی آمده است.</p>
</div>
</div>
</div>خطا
با دادن error، فیلد aria-invalid میشود و پیام خطا پیش از متن راهنما خوانده میشود.
آدرس ایمیل معتبر نیست.
<Input label="ایمیل" type="email" defaultValue="sara@example" error="آدرس ایمیل معتبر نیست." /><div class="k-field" data-invalid="">
<div class="k-field__label-row">
<label class="k-label" for=":r4R0:">ایمیل</label>
</div>
<div class="k-input" data-size="md" data-state="invalid">
<input id=":r4R0:" class="k-input__control" type="email" aria-invalid="true" aria-describedby=":r4R0:-error" value="sara@example"/>
</div>
<div class="k-field__hint-row">
<div class="k-field__hints">
<p class="k-hint k-hint--error" id=":r4R0:-error">آدرس ایمیل معتبر نیست.</p>
</div>
</div>
</div>افزونهها
ایمیل، تلفن، آدرس اینترنتی، عدد و رمز عبور بهصورت خودکار چپبهراست تایپ میشوند، ولی متن راهنمای داخل فیلد راستچین میماند.
تومان
<Input label="ایمیل" type="email" placeholder="you@example.com" addonStart={<MailIcon />} />
<Input label="مبلغ" inputMode="numeric" placeholder="۰" addonEnd="تومان" />
<Input aria-label="جستجو" placeholder="جستجو…" addonStart={<SearchIcon />} size="sm" /><div class="k-field">
<div class="k-field__label-row">
<label class="k-label" for=":r8R1:">ایمیل</label>
</div>
<div class="k-input" data-size="md"><span class="k-input__addon"><svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false" data-kashi-icon="mail"><path d="M6.5 3.75H13.5C16.7 3.75 17.5 4.55 17.5 7.75V12.25C17.5 15.45 16.7 16.25 13.5 16.25H6.5C3.3 16.25 2.5 15.45 2.5 12.25V7.75C2.5 4.55 3.3 3.75 6.5 3.75Z"/><path d="m14.1 7.6-2.9 2.35a2 2 0 0 1-2.45 0L5.85 7.6"/></svg></span>
<input id=":r8R1:" class="k-input__control" type="email" placeholder="you@example.com"/>
</div>
</div>
<div class="k-field">
<div class="k-field__label-row">
<label class="k-label" for=":r8R2:">مبلغ</label>
</div>
<div class="k-input" data-size="md">
<input id=":r8R2:" class="k-input__control" type="text" inputMode="numeric" placeholder="۰"/><span class="k-input__addon">تومان</span>
</div>
</div>
<div class="k-field">
<div class="k-input k-input--sm" data-size="sm"><span class="k-input__addon"><svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false" data-kashi-icon="search"><circle cx="9.1" cy="9.1" r="6.2"/><path d="m14.9 14.9 2.3 2.3"/></svg></span>
<input id=":r8R3:" class="k-input__control" type="text" aria-label="جستجو" placeholder="جستجو…"/>
</div>
</div>چندخطی
حداکثر ۵۰۰ نویسه.
<Textarea label="توضیحات" placeholder="چند خط بنویسید…" hint="حداکثر ۵۰۰ نویسه." /><div class="k-field">
<div class="k-field__label-row">
<label class="k-label" for=":r5R0:">توضیحات</label>
</div>
<div class="k-input k-input--textarea">
<textarea id=":r5R0:" class="k-input__control" rows="4" aria-describedby=":r5R0:-hint" placeholder="چند خط بنویسید…"></textarea>
</div>
<div class="k-field__hint-row">
<div class="k-field__hints">
<p class="k-hint" id=":r5R0:-hint">حداکثر ۵۰۰ نویسه.</p>
</div>
</div>
</div>غیرفعال
<Input label="کد ملی" defaultValue="۰۰۱۲۳۴۵۶۷۸" disabled /><div class="k-field">
<div class="k-field__label-row">
<label class="k-label" for=":r6R0:">کد ملی</label>
</div>
<div class="k-input" data-size="md" data-state="disabled">
<input id=":r6R0:" class="k-input__control" type="text" disabled="" value="۰۰۱۲۳۴۵۶۷۸"/>
</div>
</div>رمز، پاک کردن، شمارنده و بیشتر
<Input label="رمز عبور" type="password" labelEnd={<a href="/forgot">فراموشی رمز؟</a>} />
<Input aria-label="جستجو" addonStart={<SearchIcon />} clearable />
<Input label="نام کاربری" loading hint="در حال بررسی…" />
<Input label="نام شرکت" optional />
<Textarea label="دربارهٔ شما" autoResize showCount maxLength={280} />| نام | نوع | پیشفرض | توضیح |
|---|---|---|---|
type="password" | | — | دکمهٔ نمایش/پنهان کردن رمز خودکار اضافه میشود؛ با revealable={false} خاموش |
clearable / onClear | boolean / () => void | — | دکمهٔ پاک کردن وقتی فیلد مقدار دارد |
loading | boolean | false | اسپینر در انتهای فیلد |
showCount | boolean | false | شمارندهٔ نویسه؛ با maxLength به شکل «۱۲ / ۲۸۰» |
optional | boolean | string | — | نشان «(اختیاری)» کنار برچسب |
labelEnd | ReactNode | — | محتوای انتهای ردیف برچسب |
autoResize / maxRows | boolean / number | — | ارتفاع خودکار Textarea |
classNames | { root, label, box, control, addon, hint, error } | — | کلاس دلخواه برای هر بخش داخلی |
labels | { clear, show, hide, loading } | فارسی | متنهای صفحهخوان |
ویژگیها
| نام | نوع | پیشفرض | توضیح |
|---|---|---|---|
label | ReactNode | — | برچسب بالای فیلد؛ اگر نمیدهید aria-label بدهید |
hint | ReactNode | — | متن راهنمای زیر فیلد |
error | ReactNode | — | پیام خطا؛ فیلد را aria-invalid میکند |
size | "sm" | "md" | "lg" | "md" | ارتفاعها ۴۰، ۴۴ و ۴۸ پیکسل (فقط Input) |
addonStart | ReactNode | — | آیکون یا متن ابتدای فیلد (فقط Input) |
addonEnd | ReactNode | — | آیکون یا متن انتهای فیلد (فقط Input) |
fieldClassName | string | — | کلاس ظرف بیرونی k-field |
required | boolean | false | ستاره کنار برچسب و ویژگی required |
سایر ویژگیهای <input> و <textarea> به خود فیلد منتقل میشوند. ref به عنصر فیلد اشاره میکند.
متغیرهای CSS
| متغیر | پیشفرض | کاربرد |
|---|---|---|
--k-input-height-{sm,md,lg} | 2.25rem تا 2.75rem × density | ارتفاع؛ همقد دکمههای sm، md و lg |
--k-input-radius | var(--k-radius-md) | گردی گوشهها |
--k-input-bg | var(--k-bg-primary) | پسزمینه |
--k-input-border | var(--k-border-input) | رنگ حاشیه در حالت عادی |
--k-field-gap | var(--k-space-1_5) | فاصلهٔ برچسب، فیلد و راهنما |
دسترسپذیری
- حاشیهٔ فیلد کنتراست حداقل ۳ به ۱ دارد تا مرز آن برای کاربران کمبینا مشخص باشد.
- متن راهنمای داخل فیلد (placeholder) جایگزین برچسب نیست؛ با تایپ کاربر ناپدید میشود.
- پیام خطا باید بگوید چه اشتباهی رخ داده و چطور درست شود، نه فقط «نامعتبر».