Avatar

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.

Avatar API

interface AvatarProps {
  /**
   * 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";

  /**
   * 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 of the avatar. In addition to Fluent's options, CoreAI adds
   * `"neutral-alt"` so a neutral avatar can sit on either a low- or
   * high-elevation surface with appropriate contrast.
   *
   * - `"neutral"` uses `colorNeutralBackground4`
   * - `"neutral-alt"` uses `colorNeutralBackground1`
   */
  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" | "neutral-alt";

  /**
   * 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;

  ref?: Ref<HTMLSpanElement>;

  /**
   * The avatar can have a circular or square shape.
   * @default circular
   */
  shape?: "circular" | "square";

  /**
   * Size of the avatar in pixels.
   *
   * Size is restricted to a limited set of supported values recommended for most uses (see `AvatarSizeValue`) and
   * based on design guidelines for the Avatar control.
   *
   * Note: At size 16, if initials are displayed, only the first initial will be rendered.
   *
   * If a non-supported size is needed, set `size` to the next-smaller supported size, and set `width` and `height`
   * to override the rendered size.
   *
   * For example, to set the avatar to 45px in size:
   * `<Avatar size={40} style={{ width: '45px', height: '45px' }} />`
   * @default 32
   */
  size?: 16 | 20 | 24 | 28 | 32 | 36 | 40 | 48 | 56 | 64 | 72 | 96 | 120 | 128;

  style?: CSSProperties;
}