Avatar
Circular or rounded media container for user images, icons or initials text.
Aperçu
Rendu de l’aperçu en cours…
imageRendu de l’aperçu en cours…
iconRendu de l’aperçu en cours…
textRendu de l’aperçu en cours…
largeRendu de l’aperçu en cours…
roundedStructure
Anatomie
Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.
<origam-avatar> — 4 internal parts. Content priority: image wins over icon wins over text.- 1.origam-avatar
- Root element. Circle by default via
border-radius: {radius.full}. Size tokens setheightandwidth. - 2.origam-avatar__wrapper
- Inner flex container (
inline-flex; align-items: center; justify-content: center). Fills 100% of the root. - 3.origam-avatar__image
- Image container. Present only when
hasImage. WrapsOrigamImgwithoverflow: hidden; border-radius: inherit. Creates a stacking context for the negative z-index on the inner img. - 4.origam-avatar__icon / .origam-avatar__text
- Fallback content zones.
__iconwrapsOrigamIcon;__textwraps a<span>with initials. Mutually exclusive with the image zone.
API
Props
Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et description.
- icon
- MDI or custom icon rendered centered inside the avatar. Shown when no image is provided.
- imagestring | ISrcObject
- Image URL or ISrcObject (srcset / lazy-src). Takes precedence over icon and text.
- textstring
- Initials or short label rendered inside the avatar when no image or icon is set.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- Adjusts the effective avatar size via the density offset.
- Border-radius token. Default is full circle ({radius.full}).
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- Controls the avatar diameter via design tokens (24 / 32 / 40 / 48 / 56px).
- tagstring'div'
- HTML element rendered at the root.
- color
- Foreground/text color applied to the avatar surface.
- bgColor
- Background color of the avatar when no image is shown.
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>false
- Applies a border ring around the avatar.
- borderTopboolean | number | string
- borderLeftboolean | number | string
- borderBottomboolean | number | string
- borderRightboolean | number | string
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- elevationTElevation
- Box-shadow elevation token.
- hoverboolean | IStateEffectConfigfalse
- Enables hover state tracking and propagation.
- hoverClassstring
- activeboolean | IStateEffectConfigfalse
- Forces the avatar into its active/selected visual state.
- activeClassstring
- fontSizeTFontSize
- fontWeightTFontWeight
- lineHeightTLineHeight
- letterSpacingTLetterSpacing
API
Slots
Emplacements de contenu exposés par ce composant.
- #default
- Custom content rendered inside the avatar, replacing image/icon/text auto-rendering.
- #avatar
- Replaces the OrigamImg element inside the image zone.
- #icon
- Replaces the OrigamIcon element inside the icon zone.
- #text
- Replaces the text span inside the text zone.
API
Emits
Événements émis par ce composant.
- @update:activeany
- Propagates the active/selected state.
- @update:hoverboolean
- Propagates the hover state when hover tracking is enabled.
API
Membres exposés
Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.
- <T extends object>(props: T, exclude?: string[]) => Partial<T>
- Utility to forward a filtered subset of props to a child component.
- Ref<string>
- Reactive CSS string generated by useStyle from the computed avatarStyles.
- string
- Unique style-sheet ID for this instance.
- () => void
- Injects the computed style sheet. Called automatically on mount.
- () => void
- Removes the injected style sheet. Called automatically on unmount.
- Ref<boolean>
- True once the style sheet has been injected into the DOM.
Personnalisation
Variables CSS
Propriétés CSS personnalisées exposées par ce composant. Surchargez-les pour personnaliser sans perdre la compatibilité avec le thème.
- Avatar background when no image is shown. Overridden by bgColor prop and status.
- Foreground (icon/text) color. Overridden by color prop and status.
- Border radius. Full circle by default; overridden by the rounded prop.
- Avatar height. Set per size variant (24 / 32 / 40 / 48 / 56px).
- Avatar width. Set per size variant (same as height).
- Density offset subtracted from height and width. compact=+8px, comfortable=-8px.
- Icon/text font size. Set per size variant.
- Avatar box shadow. Changed to {shadow.md} when elevation is set.
Inclusion
Accessibilité
Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.
Notes
- When using the image prop, pass an ISrcObject with an alt property to provide a text alternative for screen readers. Plain string URLs result in an empty alt.
- Icon-only avatars should be wrapped in a container with an accessible label (e.g. aria-label on the parent) when they convey meaning.
- When active=true or the avatar is used in an interactive context (click handlers), wrap it in a button or add role="button" with a keyboard handler.
Fondation
Design tokens
Extrait des tokens de ce composant — les variables --origam-<composant>---<propriété>, déclarées dans sa feuille de tokens tenue à la main, sans étape de build.
- colorvar(--origam-color__surface---overlay)
- Default avatar background (when no image).
- dimensionvar(--origam-radius---full)
- Full-circle border radius by default.
- dimension40px
- Default size (40×40px).
- dimension24px
- X-small size (24×24px).
- dimension72px
- X-large size (72×72px).
- durationvar(--origam-motion__duration---medium)
- Transition duration for size, dimension and color changes.
Interactif
Playground
Modifiez les props en direct et observez le composant se mettre à jour. Le snippet de code généré suit vos changements.
Rendu de l’aperçu en cours…
Usage
Exemples
Extraits de code prêts à coller dans vos templates.
Image, icon and text
Sizes
Avatar Group
Écosystème
Famille
Composants du même dossier qui partagent les conventions et se composent souvent ensemble.