> ## 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
> Overlapping avatars with a derived overflow indicator.
export const StoryEmbed = ({storyId, title, height = 120}) => <>
Open in Storybook
;
`AvatarGroup` receives rendered avatars and derives the hidden count. `maxVisible` counts actual avatars; the overflow indicator is additional. Eight supplied avatars with `maxVisible={3}` show three avatars and `+5`.
## Usage
```tsx theme={null}
import { AvatarGroup } from 'twenty-ui/components/data-display';
import { Avatar } from 'twenty-ui/primitives/data-display';
export const TeamAvatars = () => (
(
))}
/>
);
```
Supply stable keys to keep surviving avatars mounted when the limit, total, or display order changes. Avatars are decorative by default. When the group is the only representation of its members, supply each member's name through `imageProps.alt` to label the image and default fallback. Keep avatars decorative when visible text or an owner label already supplies that identity.
## Visual options
Compare circle and square avatars at each size. The group keeps three visible members in this comparison.
## Partially loaded collections
Use `total` for the full collection size when only some avatars are loaded. Three supplied and visible avatars with `total={20}` show `+17`. Pass all loaded avatars and let the group apply `maxVisible`.
```tsx theme={null}
import { AvatarGroup } from 'twenty-ui/components/data-display';
import { Avatar } from 'twenty-ui/primitives/data-display';
export const LoadedTeamAvatars = () => (
(
))}
/>
);
```
`total` is floored and cannot be smaller than the supplied renderable avatar count. Nonfinite totals use the supplied count. The derived hidden count is always nonnegative.
`maxVisible` defaults to `4`. Finite limits are floored and clamped to zero, `Infinity` shows all supplied avatars, and `NaN` shows none. Empty React nodes do not count as avatars. A zero limit can show only the overflow indicator. An empty group with a positive total can show that total in its indicator; an empty group with no hidden avatars renders nothing.
## Custom overflow
`renderOverflow` receives the same derived hidden count as the default `+N` indicator. It runs only when that count is positive. Return `null` to hide the indicator without changing which avatars are visible.
Use an explicit control when the indicator performs an action. Its accessible name should explain the action and the count.
```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) => (
(
))}
renderOverflow={(hiddenCount) => (
)}
/>
);
```
## Appearance
Later avatars always render above earlier ones. `overlap` picks the physical margin, `left` or `right`, that carries the negative offset. `overlapOffset` sets that offset as a CSS length. `overflowShape` sets the shape of the default numeric indicator.
## Root customization
Native attributes, event handlers, `className`, and `style` reach the root. Its default element is a `div`, including when `onClick` is supplied. Use native interactive elements for actions, such as the overflow button above.
The root accepts a ref and `render`, which can be an element or a function. Custom components must forward the supplied props and ref to their native root. See [custom components](/ui/primitives/overview#custom-components) for composition requirements.
```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(null);
return (
}
avatars={['Ada', 'Grace', 'Margaret'].map((name) => (
))}
/>
);
};
```
## Props
`AvatarGroupProps` is exported from `twenty-ui/components/data-display`.
Avatar elements in display order. Empty React nodes are ignored. Supply stable keys to preserve identity when reordering.
Class applied to the group container.
Maximum number of actual avatars to show, excluding the overflow indicator. Floored and clamped to zero; Infinity shows all avatars and NaN shows none.
Shape of the numeric overflow indicator.
Physical margin, left or right, that carries the negative overlap offset. Later avatars always render above earlier ones.
CSS length of the overlap between avatars.
Ref to the rendered root element.
Element or render function for the root. Forward the supplied props and ref; the default element is a div.
Called with the derived hidden count when it is positive. Return a custom indicator, or null to hide it.
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.