Avatar

کامپوننت Avatar برای نمایش عکس پروفایل کاربر استفاده می‌شود. اگر عکسی وجود نداشته باشد یا لود آن شکست بخورد، به‌صورت خودکار محتوای جایگزین (fallback) نمایش داده می‌شود — معمولاً حروف اول نام کاربر.

Import

import { Avatar } from "fara-ui";

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

Basic Usage

<Avatar src="/avatars/user.jpg" alt="عکس سارا محمدی" fallback="س م" />

Playground

س م

sizesmmdlg

fallback

src

alt

<Avatar size="md" fallback="س م" />

Fallback

اگر src پاس نشده باشد یا لود تصویر با خطا مواجه شود، محتوای fallback به‌جای آن نمایش داده می‌شود. یک الگوی رایج، نمایش حروف اول نام کاربر است:

function initials(name) {
  return name
    .split(" ")
    .map((p) => p[0])
    .join(" ");
}

<Avatar fallback={initials("سارا محمدی")} />; // "س م"

اگر fallback را ندهی، در حالت نبودن یا خراب‌بودن تصویر، محتوای جایگزینی نمایش داده نمی‌شود. برای اطمینان از نمایش مناسب، همیشه یک fallback کوتاه مثل initials یا emoji تعیین کن.

اگر src بعد از خطای تصویر به‌صورت dynamic تغییر می‌کند، برای اطمینان از تلاش مجدد، به Avatar یک key متناسب با آدرس جدید بده؛ state خطای داخلی با تغییر src به‌طور خودکار reset نمی‌شود.

Accessibility

• alt تصویر را همیشه پاس بده تا screen reader ها نام کاربر را بخوانند؛ fallback جایگزین alt نیست.
• اندازه‌های استاندارد sm، md و lg با مقیاس ۴ پیکسلی توکن‌های طراحی هماهنگ‌اند.
• اگر Avatar فقط جنبه‌ی تزئینی دارد، alt="" مناسب است؛ اگر اطلاعات هویتی منتقل می‌کند، alt را توصیفی بنویس.

Data Attributes and Customize CSS

Avatar hookهای پایدار زیر را روی DOM قرار می‌دهد:

Attribute	کاربرد
data-fara-avatar	ریشه‌ی آواتار
data-size	اندازه‌ی فعلی: sm، md یا lg
data-fallback	وقتی تصویر نمایش داده نمی‌شود وجود دارد
data-fara-avatar-image	تصویر واقعی آواتار

<Avatar className="team-avatar" size="lg" src="/team-lead.jpg" alt="مدیر تیم" />

[data-fara-avatar][data-size="lg"] {
  box-shadow: 0 0 0 3px #dbeafe;
}

[data-fara-avatar][data-fallback] {
  background: #e0e7ff;
  color: #3730a3;
}

[data-fara-avatar-image] {
  object-position: center;
}

className روی wrapper ریشه اعمال می‌شود؛ برای هدف‌گیری تصویر یا وضعیت fallback از data attributes استفاده کن.

Props

Prop	Type	Default	Description
src	string	-	آدرس عکس پروفایل
alt	string	""	متن جایگزین تصویر
fallback	string	-	محتوای جایگزین وقتی عکس نیست یا لود نمی‌شود
size	"sm" | "md" | "lg"	"md"	اندازه‌ی آواتار
className	string	-	کلاس CSS اضافی برای سفارشی‌سازی
ref	Ref<HTMLDivElement>	-	دسترسی مستقیم به المان DOM

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