> ## 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.

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

> صور رمزية متداخلة مع مؤشر تجاوز مشتق.

## نظرة عامة

يتلقى `AvatarGroup` الصور الرمزية المعروضة ويستنتج العدد المخفي. يعدّ `maxVisible` الصور الرمزية الفعلية؛ ومؤشر التجاوز يكون إضافيًا. ثماني صور رمزية مقدمة مع `maxVisible={3}` تعرض ثلاث صور رمزية و`+5`.

**Light**

[ثماني صور رمزية مع ظهور ثلاث منها (light)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatargroup--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[ثماني صور رمزية مع ظهور ثلاث منها (dark)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatargroup--display\&viewMode=story\&globals=colorScheme:dark)

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

## استخدام

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

export const TeamAvatars = () => (
  <AvatarGroup
    maxVisible={3}
    overflowShape="circle"
    overlap="left"
    overlapOffset="4px"
    avatars={[
      'Ada',
      'Grace',
      'Margaret',
      'Annie',
      'Mary',
      'Dorothy',
      'Katherine',
      'Joan',
    ].map((name) => (
      <Avatar
        key={name}
        name={name}
        shape="circle"
        imageProps={{ alt: name }}
      />
    ))}
  />
);
```

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

## خيارات العرض

قارن بين الصور الرمزية الدائرية والمربعة في كل حجم. تحتفظ المجموعة بثلاثة أعضاء ظاهرين في هذه المقارنة.

**Light**

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

**Dark**

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

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

## المجموعات المحمّلة جزئيًا

استخدم `total` لحجم المجموعة الكامل عندما لا تكون سوى بعض الصور الرمزية محمّلة. ثلاث صور رمزية مقدمة ومرئية مع `total={20}` تعرض `+17`. مرّر جميع الصور الرمزية المحمّلة ودع المجموعة تطبّق `maxVisible`.

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

export const LoadedTeamAvatars = () => (
  <AvatarGroup
    maxVisible={3}
    total={20}
    avatars={['Ada', 'Grace', 'Margaret'].map((name) => (
      <Avatar key={name} name={name} imageProps={{ alt: name }} />
    ))}
  />
);
```

يُقرّب `total` إلى الأسفل ولا يمكن أن يكون أصغر من عدد الصور الرمزية القابلة للعرض المقدمة. تستخدم الإجماليات غير المنتهية العدد المقدّم. يكون العدد المخفي المشتق غير سالب دائمًا.

القيمة الافتراضية لـ `maxVisible` هي `4`. تُقرّب الحدود المنتهية إلى الأسفل وتُقيّد بالصفر، ويعرض `Infinity` جميع الصور الرمزية المقدمة، بينما لا يعرض `NaN` أيًا منها. لا تُحتسب عقد React الفارغة كصور رمزية. يمكن أن يعرض الحد الصفري مؤشر التجاوز فقط. يمكن لمجموعة فارغة ذات إجمالي موجب أن تعرض ذلك الإجمالي في مؤشرها؛ أما المجموعة الفارغة التي لا تحتوي على صور رمزية مخفية فلا تعرض شيئًا.

**Light**

[ثلاثة أعضاء محمّلين من فريق مكوّن من عشرين عضوًا (light)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatargroup--partially-loaded\&viewMode=story\&globals=colorScheme:light)

**Dark**

[ثلاثة أعضاء محمّلين من فريق مكوّن من عشرين عضوًا (dark)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatargroup--partially-loaded\&viewMode=story\&globals=colorScheme:dark)

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

## تجاوز مخصص

يتلقى `renderOverflow` العدد المخفي المشتق نفسه الذي يتلقاه مؤشر `+N` الافتراضي. لا يعمل إلا عندما يكون ذلك العدد موجبًا. أعد `null` لإخفاء المؤشر دون تغيير الصور الرمزية المرئية.

استخدم عنصر تحكم صريحًا عندما ينفذ المؤشر إجراءً. ينبغي أن يوضح اسمه المتاح الإجراء والعدد.

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

type TeamAvatarsWithActionProps = { onShowAll: () => void };

export const TeamAvatarsWithAction = ({
  onShowAll,
}: TeamAvatarsWithActionProps) => (
  <AvatarGroup
    maxVisible={3}
    total={20}
    avatars={['Ada', 'Grace', 'Margaret'].map((name) => (
      <Avatar key={name} name={name} imageProps={{ alt: name }} />
    ))}
    renderOverflow={(hiddenCount) => (
      <Button
        size="sm"
        aria-label={`Show ${hiddenCount} more members`}
        onClick={onShowAll}
      >
        +{hiddenCount}
      </Button>
    )}
  />
);
```

**Light**

[زر تجاوز مخصص (light)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatargroup--custom-overflow\&viewMode=story\&globals=colorScheme:light)

**Dark**

[زر تجاوز مخصص (dark)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatargroup--custom-overflow\&viewMode=story\&globals=colorScheme:dark)

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

## المظهر

تُعرَض الصور الرمزية اللاحقة دائمًا فوق الصور السابقة. يختار `overlap` الهامش الفعلي، `left` أو `right`، الذي يحمل الإزاحة السالبة. يعيّن `overlapOffset` تلك الإزاحة كطول CSS. يعيّن `overflowShape` شكل المؤشر الرقمي الافتراضي.

## تخصيص الجذر

تصل السمات الأصلية ومعالجات الأحداث و`className` و`style` إلى الجذر. عنصره الافتراضي هو `div`، بما في ذلك عند توفير `onClick`. استخدم العناصر التفاعلية الأصلية للإجراءات، مثل زر التجاوز أعلاه.

يقبل الجذر ref و`render`، والذي يمكن أن يكون عنصرًا أو دالة. يجب أن تمرّر المكونات المخصصة الـ props وref المقدمة إلى جذرها الأصلي. راجع [المكونات المخصصة](https://docs.twenty.com/ar/ui/primitives/overview#custom-components) لمتطلبات التركيب.

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

export const NamedTeamAvatars = () => {
  const groupRef = useRef<HTMLDivElement>(null);

  return (
    <AvatarGroup
      ref={groupRef}
      role="group"
      aria-label="Project members"
      style={{ marginBlock: 8 }}
      render={<div data-location="project-header" />}
      avatars={['Ada', 'Grace', 'Margaret'].map((name) => (
        <Avatar key={name} name={name} imageProps={{ alt: name }} />
      ))}
    />
  );
};
```

## الخصائص

يتم تصدير `AvatarGroupProps` من `twenty-ui/components/data-display`.

**avatars** `ReactNode[]` *required*

Avatar elements in display order. Empty React nodes are ignored. Supply stable keys to preserve identity when reordering.

**className** `string`

Class applied to the group container.

**maxVisible** `number` (default: 4)

Maximum number of actual avatars to show, excluding the overflow indicator. Floored and clamped to zero; Infinity shows all avatars and NaN shows none.

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

Shape of the numeric overflow indicator.

**overlap** `"left" | "right"` (default: right)

Physical margin, left or right, that carries the negative overlap offset. Later avatars always render above earlier ones.

**overlapOffset** `string` (default: 3px)

CSS length of the overlap between avatars.

**ref** `Ref\<HTMLDivElement\>`

Ref to the rendered root element.

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

Element or render function for the root. Forward the supplied props and ref; the default element is a div.

**renderOverflow** `((hiddenCount: number) =\> ReactNode)`

Called with the derived hidden count when it is positive. Return a custom indicator, or null to hide it.

**total** `number`

Total collection size for partially loaded avatars. Floored and never smaller than the supplied renderable count; nonfinite values use the supplied count.


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