Avatar

An image element with a fallback for representing the user.

Features

Automatic and manual control over when the image renders.
Fallback part accepts any children.
Optionally delay fallback rendering to avoid content flashing.

Installation

Install the component from your command line.

npm install @radix-ui/react-avatar

npm install @radix-ui/react-avatar

Anatomy

Import the components and piece the parts together.

import * as Avatar from '@radix-ui/react-avatar';

export default () => (
  <Avatar.Root>
    <Avatar.Image />
    <Avatar.Fallback />
  </Avatar.Root>
);

import * as Avatar from '@radix-ui/react-avatar';
export default () => (
  <Avatar.Root>
    <Avatar.Image />
    <Avatar.Fallback />
  </Avatar.Root>
);

Basic example

Create your styled avatar component from the primitive parts.

// import { styled } from 'path-to/stitches.config';
import * as Avatar from '@radix-ui/react-avatar';

const StyledAvatar = styled(Avatar.Root, {
  display: 'inline-flex',
  alignItems: 'center',
  justifyContent: 'center',
  verticalAlign: 'middle',
  overflow: 'hidden',
  userSelect: 'none',
  width: 48,
  height: 48,
  borderRadius: 24,
});

const StyledImage = styled(Avatar.Image, {
  width: '100%',
  height: '100%',
  objectFit: 'cover',
});

const StyledFallback = styled(Avatar.Fallback, {
  width: '100%',
  height: '100%',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center',
  backgroundColor: 'dodgerblue',
});

export default () => (
  <StyledAvatar>
    <StyledImage src="https://picsum.photos/id/1005/400/400" />
    <StyledFallback>UI</StyledFallback>
  </StyledAvatar>
);

// import { styled } from 'path-to/stitches.config';
import * as Avatar from '@radix-ui/react-avatar';
const StyledAvatar = styled(Avatar.Root, {
  display: 'inline-flex',
  alignItems: 'center',
  justifyContent: 'center',
  verticalAlign: 'middle',
  overflow: 'hidden',
  userSelect: 'none',
  width: 48,
  height: 48,
  borderRadius: 24,
});
const StyledImage = styled(Avatar.Image, {
  width: '100%',
  height: '100%',
  objectFit: 'cover',
});
const StyledFallback = styled(Avatar.Fallback, {
  width: '100%',
  height: '100%',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center',
  backgroundColor: 'dodgerblue',
});
export default () => (
  <StyledAvatar>
    <StyledImage src="https://picsum.photos/id/1005/400/400" />
    <StyledFallback>UI</StyledFallback>
  </StyledAvatar>
);

API Reference

Root

Contains all the parts of an avatar.

Prop	Type	Default	Required
`as`	`enum`	`span`

Image

The image to render. By default it will only render when it has loaded. You can use the onLoadingStatusChange handler if you need more control.

Prop	Type	Default	Required
`as`	`enum`	`img`
`onLoadingStatusChange`	`function`

An element that renders when the image hasn't loaded. This means whilst it's loading, or if there was an error. If you notice a flash during loading, you can provide a delayMs prop to delay its rendering so it only renders for those with slower connections. For more control, use the onLoadingStatusChange handler on Avatar.Image.

Prop	Type	Default	Required
`as`	`enum`	`span`
`delayMs`	`number`

Examples

Initials only

import * as Avatar from '@radix-ui/react-avatar';

const StyledAvatar = styled(Avatar.Root, {
  display: 'inline-flex',
  alignItems: 'center',
  justifyContent: 'center',
  verticalAlign: 'middle',
  overflow: 'hidden',
  userSelect: 'none',
  width: 48,
  height: 48,
  borderRadius: 24,
});

const StyledFallback = styled(Avatar.Fallback, {
  width: '100%',
  height: '100%',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center',
  backgroundColor: 'dodgerblue',
  fontWeight: 500,
});

export default () => (
  <StyledAvatar>
    <StyledFallback>UI</StyledFallback>
  </StyledAvatar>
);

import * as Avatar from '@radix-ui/react-avatar';
const StyledAvatar = styled(Avatar.Root, {
  display: 'inline-flex',
  alignItems: 'center',
  justifyContent: 'center',
  verticalAlign: 'middle',
  overflow: 'hidden',
  userSelect: 'none',
  width: 48,
  height: 48,
  borderRadius: 24,
});
const StyledFallback = styled(Avatar.Fallback, {
  width: '100%',
  height: '100%',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center',
  backgroundColor: 'dodgerblue',
  fontWeight: 500,
});
export default () => (
  <StyledAvatar>
    <StyledFallback>UI</StyledFallback>
  </StyledAvatar>
);

import * as Avatar from '@radix-ui/react-avatar';
import * as Tooltip from '@radix-ui/react-tooltip';

const StyledAvatar = styled(Avatar.Root, {
  display: 'inline-flex',
  alignItems: 'center',
  justifyContent: 'center',
  verticalAlign: 'middle',
  overflow: 'hidden',
  userSelect: 'none',
  width: 48,
  height: 48,
  borderRadius: 24,
  appearance: 'none',
  border: 'none',
  padding: 0,
});

const StyledImage = styled(Avatar.Image, {
  width: '100%',
  height: '100%',
  objectFit: 'cover',
});

const StyledFallback = styled(Avatar.Fallback, {
  width: '100%',
  height: '100%',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center',
  backgroundColor: 'dodgerblue',
});

const StyledTooltipTrigger = styled(Tooltip.Trigger, {
  backgroundColor: 'transparent',
  border: 'none',
  padding: 0,
});

const StyledTooltipContent = styled(Tooltip.Content, {
  borderRadius: 3,
  padding: '5px 10px',
  fontSize: 14,
  backgroundColor: 'gainsboro',
  color: 'black',
});

export default () => (
  <Tooltip.Root>
    <StyledTooltipTrigger>
      <StyledAvatar onClick={() => alert('Clicked!')}>
        <StyledImage src="https://picsum.photos/id/1006/400/400" />
        <StyledFallback>AB</StyledFallback>
      </StyledAvatar>
    </StyledTooltipTrigger>

    <StyledTooltipContent side="top">
      Tooltip content
      <Tooltip.Arrow style={{ fill: 'gainsboro' }} />
    </StyledTooltipContent>
  </Tooltip.Root>
);

import * as Avatar from '@radix-ui/react-avatar';
import * as Tooltip from '@radix-ui/react-tooltip';
const StyledAvatar = styled(Avatar.Root, {
  display: 'inline-flex',
  alignItems: 'center',
  justifyContent: 'center',
  verticalAlign: 'middle',
  overflow: 'hidden',
  userSelect: 'none',
  width: 48,
  height: 48,
  borderRadius: 24,
  appearance: 'none',
  border: 'none',
  padding: 0,
});
const StyledImage = styled(Avatar.Image, {
  width: '100%',
  height: '100%',
  objectFit: 'cover',
});
const StyledFallback = styled(Avatar.Fallback, {
  width: '100%',
  height: '100%',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center',
  backgroundColor: 'dodgerblue',
});
const StyledTooltipTrigger = styled(Tooltip.Trigger, {
  backgroundColor: 'transparent',
  border: 'none',
  padding: 0,
});
const StyledTooltipContent = styled(Tooltip.Content, {
  borderRadius: 3,
  padding: '5px 10px',
  fontSize: 14,
  backgroundColor: 'gainsboro',
  color: 'black',
});
export default () => (
  <Tooltip.Root>
    <StyledTooltipTrigger>
      <StyledAvatar onClick={() => alert('Clicked!')}>
        <StyledImage src="https://picsum.photos/id/1006/400/400" />
        <StyledFallback>AB</StyledFallback>
      </StyledAvatar>
    </StyledTooltipTrigger>
    <StyledTooltipContent side="top">
      Tooltip content
      <Tooltip.Arrow style={{ fill: 'gainsboro' }} />
    </StyledTooltipContent>
  </Tooltip.Root>
);