Skip to contents

Avatar

Source: vignettes/avatar.Rmd
avatar.Rmd

Avatars are fundamental UI elements used to represent users throughout Material Design interfaces. They appear in tables, menus, dialogs, and more. The Avatar component can display images, text initials, or icons.

Image avatars

Image avatars are created by passing src and alt properties to the Avatar() component:

muiMaterialPage(
  CssBaseline(
    Box(
      sx = list(p = 2, display = "flex", gap = 1),
      Avatar(
        alt = "Remy Sharp",
        src = "https://mui.com/static/images/avatar/1.jpg"
      ),
      Avatar(
        alt = "Travis Howard",
        src = "https://mui.com/static/images/avatar/2.jpg"
      ),
      Avatar(
        alt = "Cindy Baker",
        src = "https://mui.com/static/images/avatar/3.jpg"
      )
    )
  )
)

Letter avatars

Avatars can display text initials or single characters as children:

muiMaterialPage(
  CssBaseline(
    Box(
      sx = list(p = 2, display = "flex", gap = 1),
      Avatar("H"),
      Avatar(
        "N",
        sx = list(bgcolor = "#FF7043")
      ),
      Avatar(
        "OP",
        sx = list(bgcolor = "#7E57C2")
      )
    )
  )
)

Avatar sizes

Control avatar size using the sx prop with width and height CSS properties:

muiMaterialPage(
  CssBaseline(
    Box(
      sx = list(p = 2, display = "flex", gap = 1, alignItems = "center"),
      Avatar(
        alt = "Remy Sharp",
        src = "https://mui.com/static/images/avatar/1.jpg",
        sx = list(width = 24, height = 24)
      ),
      Avatar(
        alt = "Remy Sharp",
        src = "https://mui.com/static/images/avatar/1.jpg"
      ),
      Avatar(
        alt = "Remy Sharp",
        src = "https://mui.com/static/images/avatar/1.jpg",
        sx = list(width = 56, height = 56)
      )
    )
  )
)

Icon avatars

Use Material Design icons as avatar content:

muiMaterialPage(
  CssBaseline(
    Box(
      sx = list(p = 2, display = "flex", gap = 1),
      Avatar(
        shiny::icon("folder"),
        sx = list(bgcolor = "#E91E63")
      ),
      Avatar(
        shiny::icon("file"),
        sx = list(bgcolor = "#FF1744")
      ),
      Avatar(
        shiny::icon("image"),
        sx = list(bgcolor = "#4CAF50")
      )
    )
  )
)

Avatar variants

Change avatar shape using the variant prop. Options include:

  • "circular" (default)
  • "rounded"
  • "square"
muiMaterialPage(
  CssBaseline(
    Box(
      sx = list(p = 2, display = "flex", gap = 1),
      Avatar(
        "N",
        variant = "circular",
        sx = list(bgcolor = "#FF7043")
      ),
      Avatar(
        "N",
        variant = "rounded",
        sx = list(bgcolor = "#FF7043")
      ),
      Avatar(
        "N",
        variant = "square",
        sx = list(bgcolor = "#FF7043")
      )
    )
  )
)

Avatar fallbacks

When an image fails to load, avatars fall back in the following order:

  1. Provided children (text/icon)
  2. First letter of alt text
  3. Generic avatar icon
muiMaterialPage(
  CssBaseline(
    Box(
      sx = list(p = 2, display = "flex", gap = 1),
      # Fallback to children
      Avatar(
        alt = "Remy Sharp",
        src = "https://invalid-url.jpg",
        "B",
        sx = list(bgcolor = "#FF7043")
      ),
      # Fallback to first letter of alt
      Avatar(
        alt = "Remy Sharp",
        src = "https://invalid-url.jpg",
        sx = list(bgcolor = "#FF7043")
      ),
      # Fallback to generic icon
      Avatar(
        src = "https://invalid-url.jpg"
      )
    )
  )
)

Avatar groups

Use AvatarGroup() to stack multiple avatars. Control the maximum number displayed with the max prop:

muiMaterialPage(
  CssBaseline(
    Box(
      sx = list(p = 2, display = "flex", gap = 2),
      AvatarGroup(
        max = 4,
        Avatar(
          alt = "Remy Sharp",
          src = "https://mui.com/static/images/avatar/1.jpg"
        ),
        Avatar(
          alt = "Travis Howard",
          src = "https://mui.com/static/images/avatar/2.jpg"
        ),
        Avatar(
          alt = "Cindy Baker",
          src = "https://mui.com/static/images/avatar/3.jpg"
        ),
        Avatar(
          alt = "Agnes Walker",
          src = "https://mui.com/static/images/avatar/4.jpg"
        ),
        Avatar(
          alt = "Trevor Henderson",
          src = "https://mui.com/static/images/avatar/5.jpg"
        )
      )
    )
  )
)

Avatar group with total

Control the total number of avatars not shown using the total prop:

muiMaterialPage(
  CssBaseline(
    Box(
      sx = list(p = 2),
      AvatarGroup(
        total = 24,
        Avatar(
          alt = "Remy Sharp",
          src = "https://mui.com/static/images/avatar/1.jpg"
        ),
        Avatar(
          alt = "Travis Howard",
          src = "https://mui.com/static/images/avatar/2.jpg"
        ),
        Avatar(
          alt = "Agnes Walker",
          src = "https://mui.com/static/images/avatar/4.jpg"
        ),
        Avatar(
          alt = "Trevor Henderson",
          src = "https://mui.com/static/images/avatar/5.jpg"
        )
      )
    )
  )
)

Avatar group spacing

Control the spacing between avatars in a group using the spacing prop:

  • "small" - compact spacing
  • "medium" (default) - normal spacing
  • Numeric value - custom pixel spacing
muiMaterialPage(
  CssBaseline(
    Box(
      sx = list(p = 2, display = "flex", flexDirection = "column", gap = 2),
      Typography("Small spacing:", variant = "h6"),
      AvatarGroup(
        spacing = "small",
        Avatar(
          alt = "Remy Sharp",
          src = "https://mui.com/static/images/avatar/1.jpg"
        ),
        Avatar(
          alt = "Travis Howard",
          src = "https://mui.com/static/images/avatar/2.jpg"
        ),
        Avatar(
          alt = "Cindy Baker",
          src = "https://mui.com/static/images/avatar/3.jpg"
        )
      ),
      Typography("Medium spacing (default):", variant = "h6"),
      AvatarGroup(
        spacing = "medium",
        Avatar(
          alt = "Remy Sharp",
          src = "https://mui.com/static/images/avatar/1.jpg"
        ),
        Avatar(
          alt = "Travis Howard",
          src = "https://mui.com/static/images/avatar/2.jpg"
        ),
        Avatar(
          alt = "Cindy Baker",
          src = "https://mui.com/static/images/avatar/3.jpg"
        )
      ),
      Typography("Custom spacing (24px):", variant = "h6"),
      AvatarGroup(
        spacing = 24,
        Avatar(
          alt = "Remy Sharp",
          src = "https://mui.com/static/images/avatar/1.jpg"
        ),
        Avatar(
          alt = "Travis Howard",
          src = "https://mui.com/static/images/avatar/2.jpg"
        ),
        Avatar(
          alt = "Cindy Baker",
          src = "https://mui.com/static/images/avatar/3.jpg"
        )
      )
    )
  )
)

Avatar with Badge

Combine avatars with the Badge() component to add status indicators:

muiMaterialPage(
  CssBaseline(
    Box(
      sx = list(p = 2, display = "flex", gap = 2),
      Badge(
        overlap = "circular",
        anchorOrigin = list(vertical = "bottom", horizontal = "right"),
        variant = "dot",
        sx = list(
          "& .MuiBadge-badge" = list(
            bgcolor = "#44b700",
            boxShadow = "0 0 0 2px white"
          )
        ),
        Avatar(
          alt = "Remy Sharp",
          src = "https://mui.com/static/images/avatar/1.jpg"
        )
      ),
      Badge(
        overlap = "circular",
        anchorOrigin = list(vertical = "bottom", horizontal = "right"),
        badgeContent = Avatar(
          alt = "Remy Sharp",
          src = "https://mui.com/static/images/avatar/1.jpg",
          sx = list(width = 22, height = 22)
        ),
        Avatar(
          alt = "Travis Howard",
          src = "https://mui.com/static/images/avatar/2.jpg"
        )
      )
    )
  )
)

See the Material UI Avatar documentation and AvatarGroup documentation for complete API details.