--- package: "@svenskaspel/ui" version: "4.4.0" document_type: "component-documentation" source: "@svenskaspel/ui/docs/avatar.md" canonical_url: "/components/avatar" usage_source: "src/app/(docs)/components/avatar/page.mdx" --- # Avatar Avatar visually represents a user or entity, typically using an image, initials, or a placeholder. Indicators, such as badges or status icons, are placed with an outline to create contrast and ensure clear distinction between the Avatar and the associated information. ![Avatar](/images/components/avatar/avatar-avatar-5219-28352-0.webp) *** ## Usage The Avatar is used to visually represent users or entities in a compact and recognizable way. It is commonly applied in scenarios such as - User Profiles : Displaying a user’s photo, initials, or a placeholder when no image is available. - Collaboration Tools : Identifying team members, contributors, or participants in a group setting. - Status Indicators : Highlighting real-time information, such as online/offline status ### Avatar types The Avatar component is available in three distinct variations: Text , Image , and Signed out . Each variation suits a different user state. #### Text ![Avatar types – 1](/images/components/avatar/avatar-figma-15961.webp) When an Avatar is assigned to a user, it defaults to displaying the first letter of the user's name as the primary visual element. This ensures a clear and meaningful representation of the user, even in the absence of a custom image or icon. #### Image ![Avatar types – 2](/images/components/avatar/avatar-avatar-types-5219-28362-1.webp) When an image is provided for an Avatar, it takes precedence and replaces the default first-letter representation. The image is displayed as the primary visual element, offering a more personalized and identifiable representation of the user. ### Signed out ![Signed out](/images/components/avatar/avatar-figma-abf61.webp) The Signed Out Avatar is displayed when no user is logged in. It serves as a placeholder to indicate the absence of an active user, ensuring a consistent visual experience even in an unauthenticated state. ### Avatar sizes Avatar is available in seven sizes to suit various contexts and layouts: ![Avatar sizes](/images/components/avatar/avatar-figma-0c586.webp) 16 px – XXS 24 px – XS 32 px – S 40 px –M 48 px – L 56 px – XL 64 px – XXL *** ## Anatomy #### Text ![Text](/images/components/avatar/avatar-figma-70ccb.webp) 1. Container 2. Text #### Image ![Image – 1](/images/components/avatar/avatar-image-5219-28428-0.webp) 1. Container 2. Image #### Signed Out ![Signed Out](/images/components/avatar/avatar-figma-1e346.webp) 1. Container 2. Icon *** ## Behaviour The Avatar component dynamically adapts its appearance based on the user's state and the provided data. *** ## Placement Place Avatar consistently within layouts and adjacent to the content it identifies. *** ## Avatar with Badges The Avatar component can be enhanced with badges to provide additional context or status information about the user or entity it represents. Badges are typically displayed as a small, circular indicator overlaid on the Avatar in the top right corner. ![Avatar with Badges](/images/components/avatar/avatar-avatar-with-badges-5219-28465-0.webp) The badges are available in three distinct colours, each representing a specific purpose: - Important (Red) : Used to highlight critical or urgent information that requires immediate attention. - Attention (Yellow/Orange) : Indicates a warning or a situation that needs acknowledgment but is less urgent than "Important." - Success (Green) : Represents positive or confirmed statuses, such as "online" or "completed." - Neutral represent a less important status or add on. ### Examples #### Signed-out ![Examples](/images/components/avatar/avatar-figma-10128.webp) Signed-out avatar used to indicate a sign in call to action. #### Text ![Text – 1](/images/components/avatar/avatar-figma-6891c.webp) The "Signed-in Avatar" represents a logged-in user. By default, the Avatar displays the first letter of the user's name. #### Image ![Signed-in avatar with image](/images/components/avatar/avatar-text-5219-28479-1.webp) If the user has actively changed the Avatar to an image, the image will be shown instead. ### Best practices ![Best practices – 1](/images/components/avatar/avatar-best-practices-5219-28498-0.webp) > **Do:** Use the text or Image Avatar to represent a signed-in user. ![Best practices – 2](/images/components/avatar/avatar-best-practices-5219-28498-1.webp) > **Don't:** Don’t use the signed-out Avatar to represent signed-in users. ![Best practices – 1](/images/components/avatar/avatar-best-practices-5219-28529-0.webp) > **Do:** If the number exceeds a single digit, write it as '9+' (e.g., 9+) to indicate more. ![Best practices – 2](/images/components/avatar/avatar-best-practices-5219-28529-1.webp) > **Don't:** Don't use both icon and text in a badge — it adds clutter and disrupts its shape. Avoid full multi-digit numbers; use '9+' for clarity. *** ## Content Badges with text should be short and descriptive. Aim for one or two words that describe a state. Don’t try to include too much. --- # Readme / API # `Avatar` A versatile avatar component built with Base UI primitives and styled using Tailwind CSS via our `cn` utility. --- ## Import ```tsx import { Avatar, AvatarImage, AvatarFallback } from '@svenskaspel/ui/react/avatar'; ``` --- ## Overview - **`Avatar`** The root wrapper. Sets up the container size and shape. - **`AvatarImage`** Renders the user’s image. Falls back to the placeholder if the image fails. - **`AvatarFallback`** A styled fallback element (initials or icon) shown when the image is unavailable. --- ## Props Each sub-component accepts its corresponding Base UI props and `className`. Only the `Avatar` root accepts `size`: - **`className?: string`** Additional Tailwind or custom classes. - **`size?: 'xxs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'`** Predefined size variants: - `'xxs'` — 16×16px - `'xs'` — 24×24px - `'sm'` — 32×32px - `'md'` — 40×40px - `'lg'` — 48×48px (default) - `'xl'` — 56×56px - `'2xl'` — 80×80px ### `AvatarProps` | Prop | Type | Default | Description | | -------- | -------------------------------------------------------- | ------- | ---------------------------------------------------- | | `size` | `'xxs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` | `'lg'` | Controls the width & height of the avatar container. | | _others_ | Base UI props | — | Inherited from `Avatar.Root` (e.g., `render`, `id`). | ### `AvatarImageProps` | Prop | Type | Description | | ----- | ------------- | ----------------------------------------------------------------------------------------------------------------------- | | _all_ | Base UI props | Inherited from `Avatar.Image`. Includes `onLoadingStatusChange?: (status: 'idle' \| 'loading' \| 'loaded' \| 'error')`. | ### `AvatarFallbackProps` | Prop | Type | Default | Description | | -------- | ------------- | ------- | ---------------------------------------- | | `delay` | `number` | `0` | How long to wait, in ms, before showing. | | _others_ | Base UI props | — | Inherited from `Avatar.Fallback`. | --- ## Usage ```tsx JD ``` --- ## Accessibility - Uses Base UI’s accessible roles and attributes. - Give the image meaningful `alt` text. Give fallback content its own understandable text or accessible label; an image that failed to load does not label the fallback. --- ## Styling - Styles are applied via the `avatarStyle` variants from our utility. - Customize further with the `className` prop. --- _Enjoy your new, stylish avatars!_