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
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
Usetotal 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.
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.
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 for composition requirements.
Props
AvatarGroupProps is exported from twenty-ui/components/data-display.
ReactNode[]
required
Avatar elements in display order. Empty React nodes are ignored. Supply stable keys to preserve identity when reordering.
string
Class applied to the group container.
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.
"circle" | "rounded-square" | "square"
default:"square"
Shape of the numeric overflow indicator.
"left" | "right"
default:"right"
Physical margin, left or right, that carries the negative overlap offset. Later avatars always render above earlier ones.
string
default:"3px"
CSS length of the overlap between avatars.
Ref<HTMLDivElement>
Ref to the rendered root element.
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.
((hiddenCount: number) => ReactNode)
Called with the derived hidden count when it is positive. Return a custom indicator, or null to hide it.
number
Total collection size for partially loaded avatars. Floored and never smaller than the supplied renderable count; nonfinite values use the supplied count.