Skeleton

کامپوننت Skeleton برای نمایش جایگاه محتوای در حال بارگذاری استفاده می‌شود؛ به جای Spinner که فقط انتظار را نشان می‌دهد، Skeleton ساختار نهایی محتوا را با بلوک‌های خاکستری متحرک پیش‌نمایش می‌کند و حس سرعت بیشتری می‌دهد.

Import

import { Skeleton } from "fara-ui";

اگر هنوز FaraUI را نصب و راه‌اندازی نکرده‌ای، ابتدا صفحه‌ی شروع به کار را ببین.

Basic Usage

<div style={{ display: "grid", gap: "8px" }}>
  <Skeleton variant="text" />
  <Skeleton variant="text" width="70%" />
  <Skeleton variant="rectangle" height="120px" />
</div>

Playground

varianttextcirclerectangle

width

height

<Skeleton variant="text" />

Variant

• text (پیش‌فرض) — یک خط متن؛ ارتفاع آن با تایپوگرافی هماهنگ است
• circle — دایره؛ مناسب جایگاه عکس پروفایل یا آیکون
• rectangle — مستطیل؛ مناسب کارت، تصویر یا کادر

اندازه‌ها با width و height (مقدار CSS مثل "120px" یا "50%") تنظیم می‌شوند.

مقدار عددی نیز مجاز است و به‌عنوان مقدار عددی CSS به style می‌رود؛ برای وضوح responsive معمولاً مقدار رشته‌ای مثل "100%" یا "12rem" مناسب‌تر است. اگر style شامل width یا height باشد، مقدارهای داخل style بر propهای هم‌نام غلبه می‌کنند.

Usage Pattern

چند Skeleton را کنار هم بچین تا ساختار محتوای واقعی را شبیه‌سازی کند:

<div style={{ display: "flex", gap: "12px", alignItems: "center" }}>
  <Skeleton variant="circle" width="48px" height="48px" />
  <div style={{ flex: 1, display: "grid", gap: "8px" }}>
    <Skeleton variant="text" width="40%" />
    <Skeleton variant="text" width="80%" />
  </div>
</div>

Accessibility

• Skeleton با aria-hidden="true" پیاده شده تا برای screen reader ها نامرئی باشد.
• برای اطلاع‌رسانی وضعیت بارگذاری به کاربران keyboard/screen reader، یک role="status" (مثلاً با متن «در حال بارگذاری») در جای مناسبی از صفحه قرار بده.

<div aria-live="polite">
  <span role="status">در حال بارگذاری پروفایل...</span>
  <Skeleton variant="circle" width="48px" height="48px" />
</div>

Data Attributes and Customize CSS

Skeleton یک hook پایدار روی root خود دارد:

Attribute	کاربرد
data-fara-skeleton	root بلوک placeholder
data-variant	شکل: text، circle یا rectangle

<Skeleton className="profile-placeholder" variant="rectangle" height="180px" />

[data-fara-skeleton] {
  background: linear-gradient(90deg, #e2e8f0 25%, #f8fafc 50%, #e2e8f0 75%);
}

[data-fara-skeleton][data-variant="circle"] {
  aspect-ratio: 1;
}

@media (prefers-reduced-motion: reduce) {
  [data-fara-skeleton] {
    animation: none;
  }
}

className روی همان root اعمال می‌شود و data-variant برای استایل عمومی مبتنی بر نوع placeholder مناسب است.

Props

Prop	Type	Default	Description
variant	"text" | "circle" | "rectangle"	"text"	شکل بلوک
width	string | number	-	عرض بلوک
height	string | number	-	ارتفاع بلوک
className	string	-	کلاس CSS اضافی برای سفارشی‌سازی
style	CSSProperties	-	استایل inline اضافی

علاوه بر موارد بالا، تمام ویژگی‌های استاندارد <div> نیز پشتیبانی می‌شوند.