Avatar | Mineral UI

Avatar provides a graphic representation of an identity. It can display an image, text, or an Icon.

Examples #

Import Syntax #

import Avatar from 'mineral-ui/Avatar';

Basic Usage #

Avatar can display an image, a text character, or an Icon. For accessibility, please provide an alt/title attribute for standalone Avatars.

<DemoLayout>
  <Avatar>
    <img src="/images/avatar.svg" alt="Allison" />
  </Avatar>
  <Avatar>Allison</Avatar>
  <Avatar>
    <IconCloud title="cloud" />
  </Avatar>
</DemoLayout>

Custom Text Abbreviation #

By default, the first letter of text children will be used as the rendered abbreviated text. Pass a string to the abbr prop to provide a custom abbreviation.

<Avatar abbr="B">Dr. Bernard Johnson</Avatar>

Sizes #

Avatar is available in the following sizes.

<DemoLayout>
  <Avatar size="small">
    <img src="/images/avatar.svg" alt="Sam" />
  </Avatar>
  <Avatar size="small">Sam</Avatar>
  <Avatar size="small">
    <IconCloud title="cloud" />
  </Avatar>
  <br />

  <Avatar size="medium">
    <img src="/images/avatar.svg" alt="Melissa" />
  </Avatar>
  <Avatar size="medium">Melissa</Avatar>
  <Avatar size="medium">
    <IconCloud title="cloud" />
  </Avatar>
  <br />

  <Avatar>
    <img src="/images/avatar.svg" alt="Larry" />
  </Avatar>
  <Avatar>Larry</Avatar>
  <Avatar>
    <IconCloud title="cloud" />
  </Avatar>
  <br />

  <Avatar size="jumbo">
    <img src="/images/avatar.svg" alt="Jennifer" />
  </Avatar>
  <Avatar size="jumbo">Jennifer</Avatar>
  <Avatar size="jumbo">
    <IconCloud title="cloud" />
  </Avatar>

</DemoLayout>

Colors #

By default, Avatar will use your theme's base color. You may also pass in a custom background and/or color, but be sure to use a color combination with an adequate contrast ratio.

TRMPIBSTGBGSDC

<DemoLayout>
  <Avatar                               >Theme  </Avatar>
  <Avatar background={palette.red_60}    >Red    </Avatar>
  <Avatar background={palette.magenta_60}>Magenta</Avatar>
  <Avatar background={palette.purple_60} >Purple </Avatar>
  <Avatar background={palette.indigo_60} >Indigo </Avatar>
  <Avatar background={palette.blue_60}   >Blue   </Avatar>
  <Avatar background={palette.sky_60}    >Sky    </Avatar>
  <Avatar background={palette.teal_60}   >Teal   </Avatar>
  <Avatar background={palette.green_60}  >Green  </Avatar>
  <Avatar background={palette.bronze_60} >Bronze </Avatar>
  {/* Note that a gray background requires black, not white, text for a11y contrast */}
  <Avatar background={palette.gray_60} color={palette.black}>Gray</Avatar>
  <Avatar background={palette.slate_60}  >Slate  </Avatar>
  <Avatar background={palette.dusk_60}   >Dusk   </Avatar>
  <Avatar background="rgba(139,231,172,0.8)" color="hsl(322,71%,27%)">Custom</Avatar>
</DemoLayout>

Shapes #

Avatar is available in the following shapes.

CRS

<DemoLayout>
  <Avatar>Circle</Avatar>
  <Avatar shape="rounded">Rounded</Avatar>
  <Avatar shape="square">Square</Avatar>
</DemoLayout>

API & Theme #

Avatar Props #

The Avatar component takes the following React props.

Name	Type	Default	Description
abbr	string		When `children` is a string, this will be the rendered text
background	string		Background color
children	React$Node	required	`img` (with an `alt` attribute), Icon (with a `title`), or a string
color	string		Text color
shape	'circle' \| 'rounded' \| 'square'	'circle'	Available shapes
size	'small' \| 'medium' \| 'large' \| 'jumbo'	'large'	Available sizes

Undocumented properties, including as and css, will be applied to the root element.

Avatar Theme Variables #

These variables can be used as hooks to override this component's style at either a local or global level. The theme referenced below is whatever theme is available from props to the instance of this component.

Variable	Value
Avatar_fontSize_small	theme.fontSize_mouse
Avatar_fontSize_medium	theme.fontSize_ui
Avatar_fontSize_large	theme.h4_fontSize
Avatar_fontSize_jumbo	theme.h4_fontSize
Avatar_fontWeight	theme.fontWeight_bold
Avatar_size_small	theme.size_small
Avatar_size_medium	theme.size_medium
Avatar_size_large	theme.size_large
Avatar_size_jumbo	theme.size_jumbo

Usage #

When/How to Use #

Avatar should be used to associate something to an identity. For example, add a user's Avatar to a Card to connect that Card's content to that user.

Best Practices #

Provide an alt attribute when using Avatar to display a standalone image.

Provide a title attribute when displaying a standalone icon.

To prevent duplicate information, hide Avatar from assistive technologies with aria-hidden="true" when the associated text is sufficiently descriptive.

A Allison