Avatar
Avatar is a display element that represents an individual person.
The Basics
What it is
Avatar is a circular display element that conveys a person’s identity. It isn’t interactive by default, but it can trigger an action.
There are 3 sizes (small, medium, large) and 2 variations:
- Image displays a photo of the person.
- Initials displays the person’s first and last initial. The background color is set programmatically, based on the first initial.
How it works
- Avatar appears near other content elements to indicate the individual person or people affiliated with those elements (e.g., the author of a visit note, the last person to update a report, upcoming patients on a schedule).
- By default, Avatar is display-only, but it can include an interaction (like a link to the person’s profile).
When to use
- To indicate the author of a message, piece of data, or other content
- To select among users (like a provider group)
- To show who can access or has seen certain content
- To list the users present in an app or shared space (like a video call or a collaborative document)
When not to use
- To represent companies, objects, or other non-human entities
What to use instead
Use Icon to represent objects or items that aren’t individual people.
How to use
Avatar doesn’t have a default state. It doesn’t have any generic display features built in (like a gray background color or head graphic). You must provide Avatar with any graphics or values it should display.
Avatar works best when it contains a headshot or other image uploaded by a user. If no image data is provided, Avatar shows the person’s first and last initials. The initials are displayed against a background color, which is set programmatically based on the first initial and can’t be changed.
The image data must come from a source. The image may already be available from a source like the patient record or a user profile, but if it isn’t, you need to provide functionality for users to upload and edit images.
Because Avatar conveys a person’s identity, review your use case carefully for potential compliance, privacy, and confidentiality concerns.
Interaction
Avatar is display-only by default, but you can add a contextual interaction, like hovering to view additional information about that person or clicking to display their profile.
Include an interaction if it adds helpful information.
Add an interaction that displays redundant information.
Style
Design details
No additional information for this component.
Placement and hierarchy
No additional information for this component.
Content
Avatar includes an option for alt text. Provide this text when using Avatar to display an image. It should include the person’s name (e.g., “Photo of Laurie Aaronson”). If Avatar includes an interaction, alt text should describe the action that will take place (“Switch to view Laurie Aaronson’s profile”).
Demos
Coding
Developer tips
You must provide valid URLs for Avatar to display images.
Values for user initials
The 'initials' prop is required, even when using Avatar to show an image. Avatar needs the 'initials' data to programmatically set the background color, which is displayed if the image is broken.
Pay attention to which data fields you use as a source for the person’s initials. There may be multiple separate name fields, such as “Legal first name” and “First name used”. Use the fields that are appropriate for your use case.
Circle shape
Avatar uses the CSS property border radius
to create its circle shape (cropping the image into a circle or showing the initials in a colored circle).
Repository
Implementation links
Implementation details
It is strongly recommended to familiarize yourself with the Forge source code. While this documentation is a best effort to document the intent and usage of a component, sometimes some features only become clear when looking at the source code. Also, looking at Forge's source code may help identify and fix bugs in either your application or Forge itself.
Storybook files
Forge maintains at least one storybook file per component. While the primary audience for these files is typically the Forge team, these storybook files may cover usages of the component not covered by a demo. The storybook for the latest version of forge can be found at go/forge-storybook-lts.
Testing library
Forge strongly encourages using testing-library to write tests for your application.
"The more your tests resemble the way your software is used, the more confidence they can give you."
If you're having trouble testing a Forge component using testing-library, it would be a good idea to see how Forge tests its own components. For the most part, Forge tries to use screen.getByRole as much as it can, as that API provides the best feedback on a11y compliance. Forge discourages the use of document.querySelector and screen.getByTestId as both APIs encourage using implementation details to test your component, and discourage adding roles to your component.
With that being said, many of Forge's components were not built with accessibility in mind. These components do break the recommendations listed above.
Import statements
In Nimbus applications
athenaOne serves the Forge bundle independently from your application's bundle. Importing Forge components directly from '@athena/forge'
takes advantage of this feature.
import { Avatar } from '@athena/forge'
In standalone applications
Importing components using the exact path to the module takes advantage of webpack's tree shaking feature. Webpack will include only that module and its dependencies.
import Avatar from '@athena/forge/Avatar';
To use this import guidance, Typescript applications must use typescript >= 4.7.3
, and should add this setting to their tsconfig.json file:
{"compilerOptions": {"moduleResolution": "Node16",}}
If this setting doesn't work for your application, use this import statement instead:
import Avatar from '@athena/forge/dist/Avatar';