> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# الصورة الرمزية

> مثّل شخصًا أو سجلًا بصورة أو حرف أول أو أيقونة.

## نظرة عامة

يعرض `Avatar` صورة مع بديل للحرف الأول. استخدمه بجانب اسم سجل أو داخل [شريحة](https://docs.twenty.com/ar/ui/primitives/data-display/chip.md). العنصر الجذر الافتراضي له هو `span` للعرض.

**Light**

[مثال على Avatar (light)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatar--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[مثال على Avatar (dark)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatar--display\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-data-display-avatar--display)

## استخدام

```tsx theme={null}
import { Avatar } from 'twenty-ui/primitives/data-display';

export const WorkspaceAvatar = () => (
  <Avatar
    name="Acme"
    colorSeed="acme-app"
    shape="square"
    variant="outline"
    size="md"
  />
);
```

عند غياب الصورة أو تعذر تحميلها، يعرض البديل الحرف الأول من الاسم بعد إزالة المسافات منه، بأحرف كبيرة. يعرض الاسم الفارغ `-`. يختار `colorSeed` ألوانًا ثابتة للبديل ويكون افتراضيًا `name`؛ استخدم معرّف سجل للحفاظ على ثبات اللون عند تغيير الاسم.

الصورة والبديل الافتراضي للعودة عنصران زخرفيان. يوفر `name` الحرف الأول المرئي وألوان البديل للعودة من دون إضافة تسمية يمكن الوصول إليها. عندما تكون الصورة الرمزية هي التمثيل الوحيد لشخص أو سجل، اضبط `imageProps={{ alt: name }}` لتسمية كل من الصورة والبديل الافتراضي للعودة. أبقِ الصورة الرمزية زخرفية عندما يوفّر اسم مرئي أو مالك مُسمّى هذه المعلومات بالفعل.

يقبل `imageProps` عقد الصورة الكامل، بما في ذلك `srcSet` و`sizes` و`crossOrigin` و`referrerPolicy` والأحداث الأصلية والمراجع و`render`. تتجاوز خاصية `src` الخاصة به الاختصار `src`. يقبل `fallbackProps` عقد البديل للعودة الكامل، بما في ذلك `delay` والعناصر التابعة والتسمية والمراجع و`render`. يتولى `render` المخصص للبديل للعودة دلالات إمكانية الوصول الخاصة به؛ اضبط `aria-hidden` صراحةً عندما يكون زخرفيًا.

```tsx theme={null}
import { Avatar } from 'twenty-ui/primitives/data-display';

type RecordAvatarProps = {
  name: string;
  imageUrl?: string;
  initials: string;
};

export const RecordAvatar = ({
  name,
  imageUrl,
  initials,
}: RecordAvatarProps) => (
  <Avatar
    name={name}
    src={imageUrl}
    size="lg"
    imageProps={{ alt: name, decoding: 'async', referrerPolicy: 'no-referrer' }}
    fallbackProps={{ children: initials, delay: 150 }}
  />
);
```

## ركّب الأجزاء

استخدم `Avatar.Root` و`Avatar.Image` و`Avatar.Fallback` عندما تكون مسؤولًا عن البنية. يوفر Root الحجم والشكل ومظهر البديل للعودة؛ ولا ينشئ عناصر تابعة أو تسميات يمكن الوصول إليها.

```tsx theme={null}
import { Avatar } from 'twenty-ui/primitives/data-display';

type ContactAvatarProps = {
  name: string;
  imageUrl?: string;
  initials: string;
};

export const ContactAvatar = ({
  name,
  imageUrl,
  initials,
}: ContactAvatarProps) => (
  <Avatar.Root name={name} shape="circle" size="xxl">
    <Avatar.Image src={imageUrl} alt={name} decoding="async" />
    <Avatar.Fallback role="img" aria-label={name} delay={150}>
      {initials}
    </Avatar.Fallback>
  </Avatar.Root>
);
```

**Light**

[أجزاء الصورة الرمزية (light)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatar--parts\&viewMode=story\&globals=colorScheme:light)

**Dark**

[أجزاء الصورة الرمزية (dark)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatar--parts\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-data-display-avatar--parts)

تتشارك الأجزاء حالة تحميل الصورة في Base UI. يعرض Image عنصر `img` بعد تحميل ناجح افتراضيًا، ويعرض Fallback عنصر `span` بينما تكون الصورة غائبة أو قيد التحميل أو فشل تحميلها. تؤخر `delay` العرض الأولي للبديل للعودة بالمللي ثانية، وتكون قيمتها الافتراضية `0`. يُحمّل مصدر متغيّر مرة أخرى ويمكنه استبدال الصورة الحالية أو البديل للعودة.

يكشف `Avatar.Image` عن `onLoadingStatusChange` مع قيم الحالة `idle` و`loading` و`loaded` و`error`. يُشغَّل رد الاتصال عندما تُبلغ Base UI عن تغيّر حالة غير `idle`؛ وتؤدي إزالة تركيب جزء Image إلى إعادة تعيين حالة الجذر المشتركة إلى `idle`. تقبل Root وImage وFallback دوال `className` و`style` و`render` المدركة للحالة مع `imageLoadingStatus`؛ ويكشف Image أيضًا عن `transitionStatus`.

استخدم `keepMounted` على Image عندما يجب تحميل الصورة المعروضة في موضعها، بما في ذلك `loading="lazy"` أو مكوّن صورة محسّن. مرّر السمات والأحداث الأصلية والمرجع من مُصيّرات الصور المخصصة. قد تظل الصورة المركبة قيد التحميل أو يكون تحميلها قد فشل؛ افحص حالة التحميل بدلًا من اعتبار وجودها نجاحًا.

يدعم مُصيّر المكوّن الأمامي حاليًا مسار التحميل المسبق الافتراضي باستخدام `src`. لا تتلقى صورة المضيف الخاصة به `srcSet` أو `sizes` أو `loading` أو `decoding` أو `referrerPolicy`. قد تؤدي دالة `render` مخصصة متغيرة مع `keepMounted` إلى إبقاء صورة مفككة مخفية لأن العامل لا يمكنه قراءة حالة اكتمالها أو أبعادها. استخدم التحميل المسبق الافتراضي هناك إلى أن تتوفر إمكانات المُصيّر هذه.

تُصدَّر الأنواع العامة `AvatarRootProps` و`AvatarImageProps` و`AvatarFallbackProps` و`AvatarRootState` و`AvatarImageState` و`AvatarFallbackState` و`AvatarImageLoadingStatus` من `twenty-ui/primitives/data-display`. تستهدف المراجع عنصر DOM المعروض: `span` و`img` و`span` افتراضيًا، أو العنصر المقدم عبر `render`.

## الشكل والمظهر

**Light**

[أحجام وأشكال الصور الرمزية (light)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatar--catalog\&viewMode=story\&globals=colorScheme:light)

**Dark**

[أحجام وأشكال الصور الرمزية (dark)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatar--catalog\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-data-display-avatar--catalog)

يقبل `shape` القيم `square` أو `rounded-square` أو `circle`. الأحجام هي `xs` ‏(12px)، و`sm` ‏(14px)، و`md` ‏(16px)، و`lg` ‏(24px)، و`xl` ‏(32px)، و`xxl` ‏(40px). يستخدم كل من `xl` و`xxl` نصًا احتياطيًا بحجم 16px.

أصبح الحجم السابق `xl` البالغ 40px هو الآن `xxl`. حدّث استخدامات `size="xl"` الحالية إلى `size="xxl"` عندما ينبغي أن تظل بحجم 40px.

تضيف `variant="outline"` حدًا إلى البديل. تخصص تجاوزات `color` و`backgroundColor` و`borderColor` البديل، بينما تحافظ الصورة المحمّلة على مظهرها الأصلي.

```tsx theme={null}
import { IconUser } from 'twenty-ui/icon';
import { Avatar } from 'twenty-ui/primitives/data-display';

export const ContactIcon = () => (
  <Avatar
    icon={<IconUser />}
    shape="rounded-square"
    size="xxl"
    role="img"
    aria-label="Contact"
  />
);
```

تكون للأيقونة `icon` الأولوية على كل من الصورة والبديل ذي الحرف الأول. الأيقونة نفسها زخرفية، لذا سمِّ الجذر عندما تنقل معلومات. تُحرّك `pulsing` الشفافية وتحترم تفضيلات تقليل الحركة.

## فتح ملف شخصي

```tsx theme={null}
import { Avatar } from 'twenty-ui/primitives/data-display';

type ProfileAvatarProps = {
  onOpenProfile: () => void;
  disabled?: boolean;
};

export const ProfileAvatar = ({
  onOpenProfile,
  disabled = false,
}: ProfileAvatarProps) => (
  <Avatar
    name="Jane"
    shape="circle"
    size="lg"
    render={
      <button
        type="button"
        disabled={disabled}
        aria-label="Open Jane's profile"
        onClick={onOpenProfile}
      />
    }
  />
);
```

**Light**

[صورة رمزية مركبة كزر (light)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatar--button-composition\&viewMode=story\&globals=colorScheme:light)

**Dark**

[صورة رمزية مركبة كزر (dark)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatar--button-composition\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-data-display-avatar--button-composition)

ركّب زرًا أصليًا للإجراءات. يتولى التركيز والتنشيط بمفتاحي Enter وSpace وسلوك التعطيل. وفّر اسمًا يمكن الوصول إليه ومحددًا للإجراء. ضع `onClick` و`disabled` على الزر المعروض؛ لا تتضمن الصورة الرمزية المختصرة خاصية `onClick` أو `disabled` أو `nativeButton`.

للتنقل، ركّب رابط ارتساء مع `href` أو رابط موجه يحافظ على دلالات رابط الارتساء. تُفعّل الروابط الأصلية بمفتاح Enter. أبقِ سلوك التنقل والتعطيل مع الرابط أو المكوّن التفاعلي الذي تركّبه.

```tsx theme={null}
import { Avatar } from 'twenty-ui/primitives/data-display';

export const ProfileLink = () => (
  <Avatar
    name="Jane"
    shape="circle"
    size="lg"
    render={<a href="/people/jane" aria-label="Open Jane's profile" />}
  />
);
```

## رحّل الصور الرمزية القابلة للنقر

ركّب زرًا أصليًا عبر `render` للإجراءات، أو رابط ارتساء أو رابط موجه للتنقل. انقل `onClick` و`disabled` إلى ذلك المالك وأزل `nativeButton`. امنح المالك اسمًا مفيدًا يمكن الوصول إليه وتجنب تداخل العناصر التفاعلية. يحتفظ `Avatar.Root` والأجزاء الصريحة الأخرى بعقد أحداث Base UI الكامل.

الصور الرمزية المختصرة زخرفية افتراضيًا. لا يحدد `name` اسم الصورة أو البديل للعودة أو المالك التفاعلي. استخدم `imageProps.alt` غير فارغ فقط عندما تنقل الصورة الرمزية هوية لا يوفرها بالفعل نص مرئي أو تسمية مالك. مع الأجزاء الصريحة، وفّر النص البديل للصورة وتسميات البديل للعودة أو السمات الزخرفية بنفسك، وأبقِ المحتوى المترجم في تطبيقك.

## الخصائص

تُنشأ الأنواع والقيم الافتراضية من أنواع المكوّنات العامة. تقبل الأجزاء الصريحة السمات الأصلية ومعالجات الأحداث. تحذف الصورة الرمزية المختصرة `onClick`؛ وفّره على المالك المُمرَّر عبر `render`.

**backgroundColor** `string`

Background color override for a first-letter fallback.

**borderColor** `string`

Border color override for the outline fallback.

**className** `string | ((state: AvatarRootState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**color** `string`

Text color override for a first-letter fallback.

**colorSeed** `string`

Stable value used to choose fallback colors. Defaults to `name`.

**fallbackProps** `AvatarFallbackProps`

Complete `Avatar.Fallback` props, including caller-owned children, labeling, refs, `render`, and fallback `delay` in milliseconds.

**icon** `ReactNode`

Decorative icon rendered instead of the image and first-letter fallback. Give the root an accessible label when the icon conveys information.

**imageProps** `AvatarImageProps`

Complete `Avatar.Image` props, including native image attributes, refs, `render`, `keepMounted`, and `onLoadingStatusChange`. Alternative text defaults to an empty string. Supply a nonempty `alt` to label the image and default fallback.

**name** `string`

Name used for the first-letter fallback and fallback colors. Does not add an accessible label.

**pulsing** `boolean` (default: false)

Animates the avatar opacity. Respects reduced-motion preferences.

**render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, AvatarRootState\>`

Caller-supplied root element or renderer. Defaults to a presentational span. Compose a native button or link explicitly for interaction, and put its click handler and disabled state on that owner.

**ring** `boolean` (default: false)

Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct.

**shape** `"circle" | "rounded-square" | "square"` (default: square)

Shape of the avatar and its fallback.

**size** `"lg" | "md" | "sm" | "xl" | "xs" | "xxl"` (default: md)

Avatar size: `xs` (12px), `sm` (14px), `md` (16px), `lg` (24px), `xl` (32px), or `xxl` (40px).

**src** `string | null`

Image URL. A missing or failed image shows the fallback. `imageProps.src` overrides this value.

**style** `CSSProperties | ((state: AvatarRootState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

**variant** `"outline" | "soft"` (default: soft)

Visual treatment of the fallback.

### Avatar.Root

**Root.backgroundColor** `string`

Background color override for a first-letter fallback.

**Root.borderColor** `string`

Border color override for the outline fallback.

**Root.children** `ReactNode`

Caller-owned Image, Fallback, and other content.

**Root.className** `string | ((state: AvatarRootState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Root.color** `string`

Text color override for a first-letter fallback.

**Root.colorSeed** `string`

Stable value used to choose fallback colors. Defaults to `name`.

**Root.name** `string`

Name used to choose fallback colors. Does not add children or accessible labels.

**Root.pulsing** `boolean` (default: false)

Animates the avatar opacity. Respects reduced-motion preferences.

**Root.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, AvatarRootState\>`

Caller-supplied root element or renderer. Defaults to a presentational span. Compose a native button or link explicitly for interaction, and put its click handler and disabled state on that owner.

**Root.ring** `boolean` (default: false)

Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct.

**Root.shape** `"circle" | "rounded-square" | "square"` (default: square)

Shape of the avatar and its fallback.

**Root.size** `"lg" | "md" | "sm" | "xl" | "xs" | "xxl"` (default: md)

Avatar size: `xs` (12px), `sm` (14px), `md` (16px), `lg` (24px), `xl` (32px), or `xxl` (40px).

**Root.style** `CSSProperties | ((state: AvatarRootState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

**Root.variant** `"outline" | "soft"` (default: soft)

Visual treatment of the fallback.

### Avatar.Image

**Image.alt** `string`

Caller-owned alternative text. Use an empty string for decorative images.

**Image.className** `string | ((state: AvatarImageState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Image.crossOrigin** `"" | "anonymous" | "use-credentials"`

Native image cross-origin policy, also used during preloading.

**Image.keepMounted** `boolean` (default: false)

Keeps the image mounted and loads it in place. Loading and failed images stay hidden while Fallback is shown.

**Image.loading** `"eager" | "lazy"`

Native eager or lazy loading. Use keepMounted for lazy loading.

**Image.onLoadingStatusChange** `((status: ImageLoadingStatus) =\> void)`

Called when Base UI reports a loading, loaded, or error status. Shares that state with Root and Fallback.

**Image.referrerPolicy** `"" | "no-referrer-when-downgrade" | "no-referrer" | "origin-when-cross-origin" | "origin" | "same-origin" | "strict-origin-when-cross-origin" | "strict-origin" | "unsafe-url"`

Native image referrer policy, also used during preloading.

**Image.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<DetailedHTMLProps\<ImgHTMLAttributes\<HTMLImageElement\>, HTMLImageElement\>, AvatarImageState\>`

Replaces the image. Preserve a native image and forward the supplied attributes, events, and ref.

**Image.sizes** `string`

Native responsive image sizes used with srcSet.

**Image.src** `string`

Image URL. Image renders after a successful load unless keepMounted is enabled.

**Image.srcSet** `string`

Native responsive image source candidates.

**Image.style** `CSSProperties | ((state: AvatarImageState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

### Avatar.Fallback

**Fallback.children** `ReactNode`

Caller-owned fallback content, such as initials or an icon.

**Fallback.className** `string | ((state: AvatarFallbackState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Fallback.delay** `number` (default: 0)

Milliseconds before the initial fallback is shown. Defaults to 0.

**Fallback.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, AvatarFallbackState\>`

Replaces the fallback span. Forward the supplied props and ref, and provide its accessible label or decorative attributes.

**Fallback.style** `CSSProperties | ((state: AvatarFallbackState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.