# Avatar
## Overview
> Image: Illustration of Avatar component showing user profile representations
## When to use this component
Use `Avatar` to represent a user in your application interface. It provides a visual identity for users through profile pictures, initials, or icons.
- To display user identity in profiles, user lists, or account settings.
- To show who performed an action in activity feeds or comments.
- To represent users in collaboration features or team member lists.
- To provide visual context for user-generated content.
### Additional considerations
- Always provide a meaningful label for accessibility.
- Use consistent sizing throughout your application.
- Consider using initials when profile pictures are not available.
- Ensure proper contrast between text and background colors.
## When to use another component
- For display of non-user entities like organizations or systems, use `Image`.
- For clickable actions that aren't related to user identity, use `Button`.
```mermaid
graph TD
accDescr: Decision tree that guides on when to use the Avatar component or something else
A(Need to represent a user?) -- Yes --- B(Avatar)
A -- No --- C(Is it a non-identity action?)
C -- Yes --- D(Button)
C -- No --- E(Image)
```
### Check out
- [Image][1]
- [Button][2]
## Behaviors
### Interactive
When an `onClick` handler or `to` prop is provided, the `Avatar` becomes interactive and can be clicked to navigate or trigger actions.
> Image: Examples of interactive Avatars. The first example with heart eyes emoji shows an Avatar with a subtle hover state. The second example with grimacing emoji shows an Avatar without clear interactive feedback.
### Image fallback
When an image fails to load, the `Avatar` automatically falls back to displaying initials, providing a consistent user experience.
> Image: Examples of image fallback behavior. The first example with heart eyes emoji shows an Avatar that gracefully falls back to initials when the image fails to load. The second example with grimacing emoji shows an Avatar with a broken image placeholder.
## Usage
### Size consistency
Use consistent `Avatar` sizes throughout your application. Group related `Avatars` using the same size for visual harmony.
> Image: Examples of Avatar size consistency. The first example with heart eyes emoji shows Avatars of consistent size in a user list. The second example with grimacing emoji shows Avatars of varying sizes creating visual inconsistency.
### Color and contrast
Ensure initials have sufficient contrast against the background color for accessibility compliance. By default, the component logic handles color contrast automatically.
> Image: Examples of proper color contrast. The first example with heart eyes emoji shows Avatars with good contrast between initials and background. The second example with grimacing emoji shows Avatars with poor contrast that are difficult to read.
## Content
### Meaningful labels
Always provide descriptive labels that clearly identify what the `Avatar` represents.
> Image: Examples of meaningful Avatar labels. The first example with heart eyes emoji shows an Avatar with a clear, descriptive label like
### Initials best practices
Use 1-3 characters for initials, typically the first letter of first and last names.
> Image: Examples of proper initials usage. The first example with heart eyes emoji shows Avatars with appropriate 1-3 character initials. The second example with grimacing emoji shows Avatars with too many character initials.
### Image guidelines
Use high-quality, appropriately sized images that clearly show the person's face.
> Image: Examples of proper image usage. The first example with heart eyes emoji shows an Avatar with a clear, well-framed profile picture. The second example with grimacing emoji shows an Avatar with a low-quality or inappropriate image.
### Capitalization
Use all caps for `Avatar` labels to ensure consistency and clarity.
> Image: Examples of proper capitalization. The first example with heart eyes emoji shows an Avatar label in all caps. The second example with grimacing emoji shows an Avatar label with improper capitalization.
[1]: ./Image
[2]: ./Button
## Examples
### Basic
An Avatar can show one to three characters. You can use the `getInitials` helper to shorten a name.
```typescript
import React from 'react';
import Avatar, { getInitials } from '@splunk/react-ui/Avatar';
import Layout from '@splunk/react-ui/Layout';
export default function Basic() {
return (
);
}
```
### Image
An Avatar can show an image provided as an icon, , or asset.
```typescript
import React from 'react';
import Portrait from '@splunk/react-icons/Portrait';
import Avatar from '@splunk/react-ui/Avatar';
import Layout from '@splunk/react-ui/Layout';
import profilePicture from '../assets/profilePicture.png';
export default function Image() {
return (
}
label="Anna Yang's profile"
/>
} label="Amelia Earhart's profile" />
);
}
```
### Background color
```typescript
import React from 'react';
import Avatar from '@splunk/react-ui/Avatar';
import Layout from '@splunk/react-ui/Layout';
import { pick, variables } from '@splunk/themes';
const avatarColor = pick({
light: variables.staticA1,
dark: variables.staticA1,
});
export default function BackgroundColor() {
return (
);
}
```
### Interactive
Avatars can be interactive by including the appropriate props to make them buttons or links.
```typescript
import React from 'react';
import Avatar from '@splunk/react-ui/Avatar';
import Layout from '@splunk/react-ui/Layout';
import profilePicture from '../assets/profilePicture.png';
export default function Interactive() {
return (
}
initials="AE"
label="Amelia Earhart's profile"
onClick={() => {}}
/>
);
}
```
### Size
Avatars can be one of three standard sizes: small, medium (default), or large. The size prop can also be a string if the standard size doesn't fit your use case. Note: using a non-standard size may have unexpected layouts when combined with other components.
```typescript
import React from 'react';
import Avatar from '@splunk/react-ui/Avatar';
import Layout from '@splunk/react-ui/Layout';
export default function Size() {
return (
);
}
```
## API
### Avatar API
#### Props
| Name | Type | Required | Default | Description |
|------|------|------|------|------|
| backgroundColor | \| string \| Interpolation> \| Interpolation> | no | | All CSS color definitions are supported, such as `#223344` or `red`. Using `theme` enables the theme default. |
| elementRef | React.Ref | no | | A React ref which is set to the DOM element when the component mounts and `null` when it unmounts. |
| image | React.ReactNode | no | | The image to be displayed inside this `Avatar`, for example an `` or `