import { Meta } from '@storybook/addon-docs/blocks';

AvatarGroup Migration

Fluent UI v8 provides the Facepile control to allow users to display a list of Personas. Fluent UI v9 provides an AvatarGroup control, but has a different API.

Some key differences between Facepile and AvatarGroup are:

v9 breaks the component apart into one main component and two subcomponents:
- AvatarGroup: the main component that is in charge of the inline items displayed in the AvatarGroup.
- AvatarGroupPopover: subcomponent in charge of rendering the overflow indicator button and rendering the Popover containing the overflowing AvatarGroupItems.
- AvatarGroupItem: used instead of Personas and provides internal functionality for AvatarGroup.

v9 also provides a function partitionAvatarGroupItems that will split the items provided with the right behavior based on the layout provided. It is highly encouraged to use this function as each layout has a specific way of arranging the items.

Examples

Basic Migration

Basic usage of FacePile in v8

tsx

import React from 'react';
import { facepilePersonas } from '@fluentui/example-data';
import { Facepile, IFacepilePersona } from '@fluentui/react/lib/Facepile';
import { PersonaSize } from '@fluentui/react/lib/Persona';

const AvatarGroupV8BasicExample = () => {
  // Number of faces to display inline
  const numberOfFaces = 3;
  const personas: IFacepilePersona[] = React.useMemo(() => facepilePersonas.slice(0, numberOfFaces), [numberOfFaces]);
  const overflowPersonas = React.useMemo(() => facepilePersonas.slice(numberOfFaces), [numberOfFaces]);

  return <Facepile personaSize={PersonaSize.size32} personas={personas} overflowPersonas={overflowPersonas} />;
};

An equivalent AvatarGroup in v9 is

tsx

import * as React from 'react';
import { AvatarGroup, AvatarGroupItem, AvatarGroupPopover } from '@fluentui/react-components';

const names = [
  'Johnie McConnell',
  'Allan Munger',
  'Erik Nason',
  'Kristin Patterson',
  'Daisy Phillips',
  'Carole Poland',
  'Carlos Slattery',
  'Robert Tolbert',
  'Kevin Sturgis',
  'Charlotte Waltson',
  'Elliot Woodward',
];

const AvatarGroupV9BasicExample = () => {
  const { inlineItems, overflowItems } = partitionAvatarGroupItems({ items: names });

  return (
    <AvatarGroup {...props}>
      {inlineItems.map(name => (
        <AvatarGroupItem name={name} key={name} />
      ))}
      <AvatarGroupPopover>
        {overflowItems.map(name => (
          <AvatarGroupItem name={name} key={name} />
        ))}
      </AvatarGroupPopover>
    </AvatarGroup>
  );
};

Props Mapping

This table maps Facepile v8 props to the v9's AvatarGroup equivalent.

v8 `Facepile`	v9 `AvatarGroup`
`personas`	`children`
`addButtonProps`	-
`className`	`className`
`getPersonaProps`	`AvatarGroupItem`'s props
`maxDisplayablePersonas`	`maxAvatars` option in `partitionAvatarGroupItems`
`onRenderPersona`	Render function for the `AvatarGroupItem`
`onRenderPersonaCoin`	Render function for the `avatar` slot in `AvatarGroupItem`
`onRenderPersonaWrapper`	-
`overflowButtonProps`	`AvatarGroupPopover`'s props
`overflowButtonType`	`AvatarGroupPopover`'s `indicator` prop
`overflowPersonas`	`AvatarGroupPopover`'s children
`personaSize`	`size`
`showAddButton`	-
`showTooltip`	-
`styles`	(theme)