Avatar
Examples
Images
Initials
Custom Icons
Shapes
Avatar Groups
Importing
Slots
Properties
Events
Custom Properties
Parts
Dependencies

Avatar

<terra-avatar> | TerraAvatar

Since 1.0

stable

Avatars are used to represent a person or object.

By default, a generic icon will be shown. You can personalize avatars by adding custom icons, initials, and images. You should always provide a label for assistive devices.

<terra-avatar label="User avatar"></terra-avatar>

import TerraAvatar from '@nasa-terra/components/dist/react/avatar';

const App = () => <TerraAvatar label="User avatar" />;

Examples

Images

To use an image for the avatar, set the image and label attributes. This will take priority and be shown over initials and icons. Avatar images can be lazily loaded by setting the loading attribute to lazy.

<terra-avatar
  image="https://images.unsplash.com/photo-1446941611757-91d2c3bd3d45?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80"
  label="Avatar of the moon"
></terra-avatar>
<terra-avatar
  image="https://images.unsplash.com/photo-1635373670332-43ea883bb081?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80"
  label="Avatar of an astronaut"
  loading="lazy"
></terra-avatar>

import TerraAvatar from '@nasa-terra/components/dist/react/avatar';

const App = () => (
  <TerraAvatar
    image="https://images.unsplash.com/photo-1446941611757-91d2c3bd3d45?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80"
    label="Avatar of the moon"
  />
  <TerraAvatar
    image="https://images.unsplash.com/photo-1635373670332-43ea883bb081?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80"
    label="Avatar of an astronaut"
    loading="lazy"
  />
);

Initials

When you don’t have an image to use, you can set the initials attribute to show something more personalized than an icon.

<terra-avatar initials="JD" label="Avatar with initials: JD"></terra-avatar>

import TerraAvatar from '@nasa-terra/components/dist/react/avatar';

const App = () => <TerraAvatar initials="JD" label="Avatar with initials: JD" />;

Custom Icons

When no image or initials are set, an icon will be shown. The default avatar shows a generic “user” icon, but you can customize this with the icon slot.

<terra-avatar label="Avatar with an asteroid icon">
  <terra-icon slot="icon" name="asteroid"></terra-icon>
</terra-avatar>

<terra-avatar label="Avatar with a caret icon">
  <terra-icon slot="icon" name="caret"></terra-icon>
</terra-avatar>

<terra-avatar label="Avatar with a chevron icon">
  <terra-icon slot="icon" name="chevron-right-circle"></terra-icon>
</terra-avatar>

import TerraAvatar from '@nasa-terra/components/dist/react/avatar';
import TerraIcon from '@nasa-terra/components/dist/react/icon';

const App = () => (
  <>
    <TerraAvatar label="Avatar with an asteroid icon">
      <TerraIcon slot="icon" name="asteroid" />
    </TerraAvatar>

    <TerraAvatar label="Avatar with a caret icon">
      <TerraIcon slot="icon" name="caret" />
    </TerraAvatar>

    <TerraAvatar label="Avatar with a chevron icon">
      <TerraIcon slot="icon" name="chevron-right-circle" />
    </TerraAvatar>
  </>
);

Shapes

Avatars can be shaped using the shape attribute.

<terra-avatar shape="square" label="Square avatar"></terra-avatar>
<terra-avatar shape="rounded" label="Rounded avatar"></terra-avatar>
<terra-avatar shape="circle" label="Circle avatar"></terra-avatar>

import TerraAvatar from '@nasa-terra/components/dist/react/avatar';

const App = () => (
  <>
    <TerraAvatar shape="square" label="Square avatar" />
    <TerraAvatar shape="rounded" label="Rounded avatar" />
    <TerraAvatar shape="circle" label="Circle avatar" />
  </>
);

Avatar Groups

You can group avatars with a few lines of CSS.

<div class="avatar-group">
  <terra-avatar
    image="https://images.unsplash.com/photo-1710267224163-0ee7e0d7a7ce?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&q=80&crop=right"
    label="Avatar 1 of 3"
  ></terra-avatar>

  <terra-avatar
    image="https://images.unsplash.com/photo-1446941611757-91d2c3bd3d45?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80"
    label="Avatar 2 of 3"
  ></terra-avatar>

  <terra-avatar
    image="https://images.unsplash.com/photo-1635373670332-43ea883bb081?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80"
    label="Avatar 3 of 3"
  ></terra-avatar>
</div>

<style>
  .avatar-group terra-avatar:not(:first-of-type) {
    margin-left: -1rem;
  }

  .avatar-group terra-avatar::part(base) {
    border: solid 2px var(--terra-color-spacesuit-white);
  }
</style>

import TerraAvatar from '@nasa-terra/components/dist/react/avatar';

const css = `
  .avatar-group terra-avatar:not(:first-of-type) {
    margin-left: -1rem;
  }

  .avatar-group terra-avatar::part(base) {
    border: solid 2px var(--terra-color-spacesuit-white);
  }
`;

const App = () => (
  <>
    <div className="avatar-group">
      <TerraAvatar
        image="https://images.unsplash.com/photo-1710267224163-0ee7e0d7a7ce?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&q=80&crop=right"
        label="Avatar 1 of 3"
      />

      <TerraAvatar
        image="https://images.unsplash.com/photo-1446941611757-91d2c3bd3d45?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80"
        label="Avatar 2 of 3"
      />

      <TerraAvatar
        image="https://images.unsplash.com/photo-1635373670332-43ea883bb081?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80"
        label="Avatar 3 of 3"
      />
    </div>

    <style>{css}</style>
  </>
);

[component-metadata:terra-avatar]

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script

Import

Bundler

React

To import this component from the CDN using a script tag:

<script type="module" src="https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/avatar/avatar.js"></script>

To import this component from the CDN using a JavaScript import:

import 'https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/avatar/avatar.js';

To import this component using a bundler:

import '@nasa-terra/components/dist/components/avatar/avatar.js';

To import this component as a React component:

import TerraAvatar from '@nasa-terra/components/dist/react/avatar';

Slots

Name	Description
`icon`	The default icon to use when no image or initials are present. Works best with `<terra-icon>`.

Learn more about using slots.

Properties

Name	Description	Type	Default
`image`	The image source to use for the avatar.	`string`	`''`
`label`	A label to use to describe the avatar to assistive devices.	`string`	`''`
`initials`	Initials to use as a fallback when no image is available (1–2 characters max recommended).	`string`	`''`
`loading`	Indicates how the browser should load the image.	`'eager' \| 'lazy'`	`'eager'`
`shape`	The shape of the avatar.	`'circle' \| 'square' \| 'rounded'`	`'circle'`
`updateComplete`	A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name	React Event	Description	Event Detail
`terra-error`	`onTerraError`	The image could not be loaded. This may because of an invalid URL, a temporary network condition, or some unknown cause.	-

Learn more about events.

Custom Properties

Name	Description	Default
`--size`	The size of the avatar.

Learn more about customizing CSS custom properties.

Parts

Name	Description
`base`	The component’s base wrapper.
`icon`	The container that wraps the avatar’s icon.
`initials`	The container that wraps the avatar’s initials.
`image`	The avatar image. Only shown when the `image` attribute is set.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

<terra-icon>