Avatar
Circular or rounded media container for user images, icons or initials text.
Preview
Rendering the live preview…
imageRendering the live preview…
iconRendering the live preview…
textRendering the live preview…
largeRendering the live preview…
roundedStructure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<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
All props accepted by this component, with their type, default value and 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
Content slots exposed by this component.
- #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
Events emitted by this component.
- @update:activeany
- Propagates the active/selected state.
- @update:hoverboolean
- Propagates the hover state when hover tracking is enabled.
API
Exposed members
Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.
- <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.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- 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
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
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.
Foundation
Design tokens
Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.
- 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.
Interactive
Playground
Edit props live and see the component update in real time. The generated code snippet updates as you change values.
Rendering the live preview…
Usage
Examples
Ready-to-paste code snippets for your templates.
Image, icon and text
Sizes
Avatar Group
Ecosystem
Family
Components from the same folder that share conventions and often compose together.