Avatar group

API

Generated CoreAI prop summaries, not replacement type declarations. Most native DOM/event and ARIA props are omitted. ? means optional; JSDoc shows defaults, deprecations, and conditional requirements. Defaults assume the standard CoreAI provider.

AvatarGroup API

The AvatarGroup component represents a group of multiple people or entities by taking care of the arrangement of individual Avatars in a spread, stack, or pie layout.

interface AvatarGroupProps {
  as?: "div";

  children?: any;

  className?: string;

  /**
   * Layout the AvatarGroupItems should be displayed as.
   * @default spread
   */
  layout?: "spread" | "stack" | "pie";

  ref?: Ref<HTMLDivElement>;

  /**
   * Size of the AvatarGroupItems.
   * @default 32
   */
  size?: 16 | 20 | 24 | 28 | 32 | 36 | 40 | 48 | 56 | 64 | 72 | 96 | 120 | 128;

  style?: CSSProperties;
}

AvatarGroupItem API

The AvatarGroupItem component represents a single person or entity. AvatarGroupItem should only be used in an AvatarGroup component.

interface AvatarGroupItemProps {
  /**
   * Optional activity indicator
   * * active: the avatar will be decorated according to activeAppearance
   * * inactive: the avatar will be reduced in size and partially transparent
   * * unset: normal display
   * @default unset
   */
  active?: "active" | "inactive" | "unset";

  /**
   * The appearance when `active="active"`
   * @default ring
   */
  activeAppearance?: "ring" | "shadow" | "ring-shadow";

  as?: "span";

  /**
   * Avatar that represents a person or entity.
   */
  avatar?: NonNullable<WithSlotShorthandValue<Omit<ComponentProps<AvatarSlots>, "color"> & { active?: "active" | "inactive" | "unset"; activeAppearance?: "ring" | "shadow" | "ring-shadow"; color?: "brand" | "neutral" | "colorful" | AvatarNamedColor | undefined; idForColor?: string | undefined; name?: string | undefined; shape?: AvatarShape | undefined; size?: AvatarSize | undefined; } & RefAttributes<HTMLSpanElement>> | null> | undefined;

  /**
   * Badge to show the avatar's presence status.
   */
  badge?: WithSlotShorthandValue<Omit<ComponentProps<Pick<BadgeSlots, "root" | "icon">>, "color"> & Pick<BadgeProps, "size"> & { status?: PresenceBadgeStatus; outOfOffice?: boolean; } & RefAttributes<HTMLDivElement>> | null | undefined;

  children?: any;

  className?: string;

  /**
   * The color when displaying either an icon or initials.
   * * neutral (default): gray
   * * brand: color from the brand palette
   * * colorful: picks a color from a set of pre-defined colors, based on a hash of the name (or idForColor if provided)
   * * [AvatarNamedColor]: a specific color from the theme
   * @default neutral
   */
  color?: "anchor" | "brand" | "neutral" | "colorful" | "dark-red" | "cranberry" | "red" | "pumpkin" | "peach" | "marigold" | "gold" | "brass" | "brown" | "forest" | "seafoam" | "dark-green" | "light-teal" | "teal" | "steel" | "blue" | "royal-blue" | "cornflower" | "navy" | "lavender" | "purple" | "grape" | "lilac" | "pink" | "magenta" | "plum" | "beige" | "mink" | "platinum";

  /**
   * Icon to be displayed when the avatar doesn't have an image or initials.
   * @default `PersonRegular` (the default icon's size depends on the Avatar's size)
   */
  icon?: WithSlotShorthandValue<{ as?: "span"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & { ref?: ((instance: HTMLSpanElement | null) => void) | RefObject<HTMLSpanElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  /**
   * Specify a string to be used instead of the name, to determine which color to use when color="colorful".
   * Use this when a name is not available, but there is another unique identifier that can be used instead.
   */
  idForColor?: string;

  /**
   * The Avatar's image.
   *
   * Usage e.g.: `image={{ src: '...' }}`
   */
  image?: ({ as?: "img"; } & Omit<Omit<DetailedHTMLProps<ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>, "ref"> & { ref?: ((instance: HTMLImageElement | null) => void) | RefObject<HTMLImageElement> | null; }, "children"> & { children?: undefined; }) | null | undefined;

  /**
   * (optional) Custom initials.
   *
   * It is usually not necessary to specify custom initials; by default they will be derived from the `name` prop,
   * using the `getInitials` function.
   *
   * The initials are displayed when there is no image (including while the image is loading).
   */
  initials?: WithSlotShorthandValue<{ as?: "span"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & { ref?: ((instance: HTMLSpanElement | null) => void) | RefObject<HTMLSpanElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  /**
   * The name of the person or entity represented by this Avatar. This should always be provided if it is available.
   *
   * The name is used to determine the initials displayed when there is no image. It is also provided to
   * accessibility tools.
   */
  name?: string;

  /**
   * Label used for the name of the AvatarGroupItem when rendered as an overflow item.
   * The content of the label, by default, is the `name` prop from the `avatar` slot.
   */
  overflowLabel?: NonNullable<WithSlotShorthandValue<{ as?: "span"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & { ref?: ((instance: HTMLSpanElement | null) => void) | RefObject<HTMLSpanElement> | null; }, "children"> & { children?: any; }> | null> | undefined;

  ref?: Ref<HTMLSpanElement>;

  root?: NonNullable<WithSlotShorthandValue<{ as?: "div"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null; }, "children"> & { children?: any; }> | ({ as: "li"; } & Omit<Omit<DetailedHTMLProps<LiHTMLAttributes<HTMLLIElement>, HTMLLIElement>, "ref"> & { ref?: ((instance: HTMLLIElement | null) => void) | RefObject<HTMLLIElement> | null | undefined; }, "children"> & { children?: any; }) | null> | undefined;

  style?: CSSProperties;
}

AvatarGroupPopover API

The AvatarGroupPopover component provides a button with a Popover containing the children provided.

interface AvatarGroupPopoverProps {
  /**
   * A popover can appear styled with brand or inverted.
   * When not specified, the default style is used.
   */
  appearance?: "brand" | "inverted";

  children: ReactNode;

  /**
   * Flag to close the Popover when an iframe outside a PopoverSurface is focused
   * @default true
   */
  closeOnIframeFocus?: boolean;

  /**
   * Close when scroll outside of it
   * @default false
   */
  closeOnScroll?: boolean;

  /**
   * List that contains the overflowed AvatarGroupItems.
   */
  content?: NonNullable<WithSlotShorthandValue<{ as?: "ul"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLUListElement>, HTMLUListElement>, "ref"> & { ref?: ((instance: HTMLUListElement | null) => void) | RefObject<HTMLUListElement> | null; }, "children"> & { children?: any; }> | null> | undefined;

  /**
   * Number of AvatarGroupItems that will be rendered.
   *
   * Note: AvatarGroupPopover handles counting the number of children, but when using a react fragment to wrap the
   * children, this is not possible and therefore it has do be added manually.
   */
  count?: number;

  /**
   * Used to set the initial open state of the Popover in uncontrolled mode
   * @default false
   */
  defaultOpen?: boolean;

  /**
   * Whether the triggerButton should render an icon instead of the number of overflowed AvatarGroupItems.
   * Note: The indicator will default to `icon` when the size is less than 24.
   * @default count
   */
  indicator?: "icon" | "count";

  /**
   * Enables standard behavior according to the [HTML dialog spec](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/showModal)
   * where the focus trap involves setting outside elements inert,
   * making navigation leak from the trapped area back to the browser toolbar and vice-versa.
   * @default false
   */
  inertTrapFocus?: boolean;

  /**
   * Popovers are rendered out of DOM order on `document.body` by default, use this to render the popover in DOM order
   * @default false
   */
  inline?: boolean;

  /**
   * Must be used with the `trapFocus` prop
   * Enables older Fluent UI focus trap behavior where the user
   * cannot tab into the window outside of the document. This is now
   * non-standard behavior according to the [HTML dialog spec](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/showModal)
   * where the focus trap involves setting outside elements inert.
   * @deprecated this behavior is default provided now, to opt-out of it in favor of standard behavior use the `inertTrapFocus` property
   */
  legacyTrapFocus?: boolean;

  /**
   * Where the portal children are mounted on DOM
   * @default a new element on document.body without any styling
   */
  mountNode?: HTMLElement | { element?: HTMLElement | null; className?: string; } | null | undefined;

  /**
   * Sets the delay for closing popover on mouse leave
   */
  mouseLeaveDelay?: number;

  /**
   * Call back when the component requests to change value
   * The `open` value is used as a hint when directly controlling the component
   */
  onOpenChange?: ((e: OpenPopoverEvents, data: OnOpenChangeData) => void);

  /**
   * Controls the opening of the Popover
   * @default false
   */
  open?: boolean;

  /**
   * Flag to open the Popover as a context menu. Disables all other interactions
   * @default false
   */
  openOnContext?: boolean;

  /**
   * Flag to open the Popover by hovering the trigger
   * @default false
   */
  openOnHover?: boolean;

  /**
   * PopoverSurface that contains the content.
   */
  popoverSurface?: NonNullable<WithSlotShorthandValue<Omit<PopoverSurfaceSlots, "root"> & Omit<{ as?: "div"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null; }, "children"> & { children?: any; }, "ref"> & RefAttributes<HTMLDivElement>> | null> | undefined;

  /**
   * Configures the position of the Popover.
   * Explore [Positioning docs](https://react.fluentui.dev/?path=/docs/concepts-developer-positioning-components--docs) for more options.
   */
  positioning?: PositioningShorthand;

  /**
   * Determines popover padding and arrow size
   * @default medium
   */
  size?: "small" | "medium" | "large";

  /**
   * Slot for the surface motion animation.
   * For more information refer to the [Motion docs page](https://react.fluentui.dev/?path=/docs/motion-motion-slot--docs).
   */
  surfaceMotion?: PresenceMotionSlotProps | null;

  /**
   * Tooltip shown when triggerButton is hovered.
   */
  tooltip?: NonNullable<WithSlotShorthandValue<TooltipProps> | null>;

  /**
   * Should trap focus
   * @default false
   */
  trapFocus?: boolean;

  /**
   * Button that triggers the Popover.
   */
  triggerButton?: NonNullable<WithSlotShorthandValue<{ as?: "button"; } & Omit<Omit<DetailedHTMLProps<ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & { ref?: ((instance: HTMLButtonElement | null) => void) | RefObject<HTMLButtonElement> | null; }, "children"> & { children?: any; }> | null> | undefined;

  /**
   * By default Popover focuses the first focusable element in PopoverSurface on open.
   * Specify `disableAutoFocus` to prevent this behavior.
   * @default false
   */
  unstable_disableAutoFocus?: boolean;

  /**
   * Display an arrow pointing to the target.
   * @default false
   */
  withArrow?: boolean;
}