diff --git a/docs/data/joy/components/avatar/FallbackAvatars.js b/docs/data/joy/components/avatar/FallbackAvatars.js index ad9de295481356..8a605a3ec62b26 100644 --- a/docs/data/joy/components/avatar/FallbackAvatars.js +++ b/docs/data/joy/components/avatar/FallbackAvatars.js @@ -6,7 +6,7 @@ export default function FallbackAvatars() { return ( - B + BT diff --git a/docs/data/joy/components/avatar/FallbackAvatars.tsx b/docs/data/joy/components/avatar/FallbackAvatars.tsx index ad9de295481356..8a605a3ec62b26 100644 --- a/docs/data/joy/components/avatar/FallbackAvatars.tsx +++ b/docs/data/joy/components/avatar/FallbackAvatars.tsx @@ -6,7 +6,7 @@ export default function FallbackAvatars() { return ( - B + BT diff --git a/docs/data/joy/components/avatar/FallbackAvatars.tsx.preview b/docs/data/joy/components/avatar/FallbackAvatars.tsx.preview index 4909c1039443d1..fbf311584f0550 100644 --- a/docs/data/joy/components/avatar/FallbackAvatars.tsx.preview +++ b/docs/data/joy/components/avatar/FallbackAvatars.tsx.preview @@ -1,5 +1,5 @@ - B + BT \ No newline at end of file diff --git a/docs/data/joy/components/avatar/avatar.md b/docs/data/joy/components/avatar/avatar.md index 3408b2d91ebf15..efb136b051115c 100644 --- a/docs/data/joy/components/avatar/avatar.md +++ b/docs/data/joy/components/avatar/avatar.md @@ -6,11 +6,11 @@ githubLabel: 'component: avatar' # Avatar -

Avatar represents a person that contains an image or initials which can also be presented in a group with multiple avatars.

+

An avatar is a graphical representation of a user's identity.

## Introduction -The avatar component is usually seen for displaying user information in places such as menus, tables, and chats. +The Avatar component can be used to display graphical information about a user in places such as menus, tables, and chats. {{"demo": "AvatarUsage.js", "hideToolbar": true}} @@ -28,58 +28,76 @@ export default function MyApp() { } ``` -### Sizes - -The avatar components comes with three sizes out of the box: `sm`, `md` (the default), and `lg`. - -{{"demo": "AvatarSizes.js"}} +## Basics -:::success -To learn how to add more sizes to the component, check out [Themed components—Extend sizes](/joy-ui/customization/themed-components/#extend-sizes). -::: +By default, the Avatar component displays a generic Person Icon. +Wrap it around a string to display plain text, or use the `src` prop to display an image. -### Variants +## Anatomy -The avatar component supports the four global variants: `soft` (default), `solid`, `outlined`, and `plain`. +The Avatar component is composed of a root `
` that may wrap around an ``, an ``, or a string: -{{"demo": "AvatarVariants.js"}} +```html +
+ +
+``` -:::success -To learn how to add more variants to the component, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants). -::: +## Customization -### Initials +### Text Avatar -Use a string as children to display its initials on the avatar component. +Wrap the Avatar component around a string to display text. +Note that the Avatar is designed to comfortably fit two letters at most—for instance, a user's initials: {{"demo": "InitialAvatars.js"}} -### Image +### Image Avatar -Insert images in the avatar by using a path inside the `src` prop, similar to how you'd do in the HTML `` element. -Make sure to to write a meaningful description in the `alt` prop. +Insert images into the Avatar by defining a path inside the `src` prop, just like you would with an HTML `` element. +Make sure to to write a meaningful description for the `alt` prop. {{"demo": "ImageAvatars.js"}} ### Image fallbacks -If an error occurs while loading the avatar image, it will fallback to alternatives in the following order: +If an error occurs while loading the Avatar's image, it will fall back to the following alternatives (in this order): -1. The provided children string. -2. The first letter of the `alt` text. -3. A generic icon. +1. The provided child string +2. The first letter of the alt text +3. The default generic icon {{"demo": "FallbackAvatars.js"}} -### With a badge +### Variants + +The Avatar component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `soft` (default), `solid`, `outlined`, and `plain`. + +{{"demo": "AvatarVariants.js"}} + +:::success +To learn how to add more variants to the component, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants). +::: + +### Sizes -Combine the avatar component with the [`Badge`](/joy-ui/react-badge/) to extend what you can communicate with it. +The Avatar component comes in three sizes: `sm`, `md` (the default), and `lg`: + +{{"demo": "AvatarSizes.js"}} + +:::success +To learn how to add custom sizes to the component, check out [Themed components—Extend sizes](/joy-ui/customization/themed-components/#extend-sizes). +::: + +## Usage with the Badge + +Combine the Avatar component with the [Badge](/joy-ui/react-badge/) to visually communicate more complex information about a user's status: {{"demo": "BadgeAvatars.js"}} -### Group +## Usage with the Avatar Group -Use `AvatarGroup` component to group multiple avatars together. +Use the Avatar Group component to group multiple Avatars together. ```jsx import AvatarGroup from '@mui/joy/AvatarGroup'; @@ -89,44 +107,43 @@ import AvatarGroup from '@mui/joy/AvatarGroup'; ### Quantity within a group -The `AvatarGroup` does not provide built-in props to control the maximum and the total number of avatars within a group. -This is because customization is broader if you have full control of the logic. +The Avatar Group does not provide built-in props to control the maximum or the total number of Avatars within a group. +This is intentionally left open-ended to give you broader options for customization. -Use the snippet below as insipiration to create that: +The demo below shows an example of an Avatar Group that maxes out at five; all Avatars beyond the first four are lumped together in the fifth Avatar, which displays the total number hidden: {{"demo": "MaxAndTotalAvatars.js"}} -### Ellipsis action +### Consistent appearance -`Avatar` exposes meaningful CSS variables to communicate with `AvatarGroup`. -You can apply those variables to other components to mimic the avatar appearance inside a group. -This customization technique makes your interface more resilient to changes. +The Avatar component exposes meaningful CSS variables to communicate with Avatar Group. +You can apply those variables to other non-Avatar components to mimic the Avatar's appearance inside of a group. +This customization technique makes your interface more resilient to changes, as any style changes applied to the Avatar will also be applied to the other components in the group. -Here is an example of using `IconButton` component to create an ellipsis action: +Here is an example using an Icon Button with its styles defined by the Avatar's CSS variables: {{"demo": "EllipsisAvatarAction.js"}} ### Overlapping order -By default, the first avatar in the group stays behind the second and so on. -You can reverse the overlapping order by reversing avatars position and using the CSS `flexDirection: row-reverse` property in the `AvatarGroup`. +By default, the first Avatar in the group sits behind the second, which sits behind the third, and so on. +You can reverse the overlapping order by reversing the order of the Avatars and using the CSS `flexDirection: row-reverse` property in the Avatar Group: {{"demo": "OverlapAvatarGroup.js"}} -### Vertical +### Vertical stacking -To render the `AvatarGroup` vertically, add the CSS `writing-mode: vertical-rl` property to the it and rotate the extra element, if existent, by -90 degrees. +To render the Avatar Group vertically, add the CSS `writing-mode: vertical-rl` property and rotate the interior element (if one is present) by -90 degrees. :::info -**Tip:** Give preference to this approach as it preserves the overlapping offset between avatars whereas `flexDirection: column` don't. +This approach is preferable because it preserves the overlapping offset between Avatars; the alternative—`flexDirection: column`—does not. ::: {{"demo": "VerticalAvatarGroup.js"}} -## CSS variables - -Play around with all the CSS variables available in the slider component to see how the design changes. +## CSS variable playground -You can use those to customize the component on both the `sx` prop and the theme. +Play around with the CSS variables available to the Avatar component to see how the design changes. +You can use these to customize the component with both the `sx` prop and the theme. {{"demo": "AvatarGroupVariables.js", "hideToolbar": true }}