Skip to content

OrigamAvatar ​

<OrigamAvatar> is the polymorphic identity glyph for origam. It can render an image, an icon, or a text initial inside a sized chip with the full chrome mixin set (size, density, color, status, rounded, border, elevation, hover/active feedback, padding, margin).

It is the building block of OrigamAvatarGroup and is what OrigamBtn consumes through its prepend-avatar / append-avatar slots.

Basic usage ​

Pick one of the three content modes — image, icon, or text. The fall-through priority is image > icon > text, so passing several at the same time renders only the first available.

vue
<template>
    <OrigamAvatar text="AP" />
    <OrigamAvatar :icon="MDI_ICONS.ACCOUNT" />
    <OrigamAvatar image="https://picsum.photos/seed/origam-av/120/120" />
</template>

Sizes ​

size follows the shared origam ladder. Each step bumps width, height and font-size atomically so the avatar never becomes lopsided.

SizePixels
x-small24
small32
default40
large48
x-large56
vue
<template>
    <OrigamAvatar size="x-small" text="XS" />
    <OrigamAvatar size="small"   text="SM" />
    <OrigamAvatar size="default" text="MD" />
    <OrigamAvatar size="large"   text="LG" />
    <OrigamAvatar size="x-large" text="XL" />
</template>

Density ​

Density shaves 8 pixels off both axes (compact / comfortable behave the same — they remap to the same SCSS variable on purpose, so the host can override one without touching the other).

vue
<template>
    <OrigamAvatar density="default"     text="DF" />
    <OrigamAvatar density="compact"     text="CP" />
    <OrigamAvatar density="comfortable" text="CF" />
</template>

Color (intent) ​

color and bg-color map to the semantic intent ladder. color drives the foreground (initials + icon stroke), bg-color drives the chip background. Use :style for one-off custom hexes.

vue
<template>
    <OrigamAvatar bg-color="primary"   text="P" />
    <OrigamAvatar bg-color="success"   text="S" />
    <OrigamAvatar bg-color="warning"   text="W" />
    <OrigamAvatar bg-color="danger"    text="D" />
</template>

Foreground auto-derives from an intent bgColor (#819) ​

When bg-color is a recognised intent (neutral / primary / secondary / success / warning / danger / info), Avatar always paints text with that intent's own WCAG-AA audited foreground — even if a color prop or a brand theme default supplied a different, fixed value. This exists because bg-color is the one prop Avatar consumers routinely vary per instance (initials/colors generated per user or team member) while color is typically a single theme-wide default; without this, a fixed color can go unreadable the moment an instance's bg-color swaps to an intent it was never paired against (measured as low as 1.25:1 in production brand themes).

ghost is the one exception — its background is always transparent (every intent ladder, not a per-theme choice): its own foreground is tuned as a link/icon accent against an arbitrary surface, not as a background-pill pairing, so bg-color="ghost" is left to resolve exactly as before. Setting color to one of the 8 named intents (a deliberate two-intent combination, e.g. bg-color="secondary" color="primary") is also left untouched — only a fixed/legacy (hex, var(), raw CSS) color is overridden. A custom (non-intent) bg-color is never touched either — there is no audited pairing to derive from, and the existing auto-contrast fallback (getForeground) still applies when no color is set at all.

Status ​

Pass status to apply one of the feedback intents. The component reads the same --origam-color__feedback--{intent}---{bg|fg} semantic tokens as the rest of origam, so theme switches stay coherent.

vue
<template>
    <OrigamAvatar status="success" text="OK" />
    <OrigamAvatar status="warning" text="!"  />
    <OrigamAvatar status="error"   text="X"  />
    <OrigamAvatar status="info"    text="?"  />
</template>

Rounded ​

The avatar is fully circular by default (border-radius: 50%). Use rounded to switch to one of the named rungs (x-small, small, default, medium, large, x-large) for a square-with-corners look.

vue
<template>
    <OrigamAvatar text="AP" />
    <OrigamAvatar text="AP" rounded="default" />
    <OrigamAvatar text="AP" rounded="x-large" />
    <OrigamAvatar text="AP" :rounded="false" />
</template>

Elevation ​

elevation applies the shared shadow ladder (xs / sm / md / lg / xl). Useful for floating-status avatars on top of cards.

vue
<template>
    <OrigamAvatar text="AP" :elevation="4" />
    <OrigamAvatar text="AP" :elevation="8" />
</template>

Border ​

Pass the border mixin to draw a thin outline around the chip — handy for layering on coloured surfaces.

vue
<template>
    <OrigamAvatar text="AP" border />
</template>

Hover / active ​

Like every origam atom that consumes the hover + active mixins, the avatar can be wired to interactive feedback. The classes are emitted even when the avatar is purely decorative — only style cost, no event listeners attached.

vue
<template>
    <OrigamAvatar text="AP" hover active />
</template>

Polymorphic tag ​

The avatar renders a <div> by default. Switch the tag for menus and clickable contexts:

vue
<template>
    <OrigamAvatar tag="button" text="AP" @click="onClick" />
    <OrigamAvatar tag="a" text="AP" href="/profile" />
</template>

Slots ​

SlotSlot propsDescription
default—Full content override.
avatar—Custom rendering when image is provided.
icon—Custom rendering when icon is provided.
text—Custom rendering when text is provided.

Events ​

EventPayloadDescription
update:activebooleanActive state toggled on click.
update:hoverbooleanHover state toggled on mouse enter / leave.

Props (interface) ​

ts
interface IAvatarProps extends ICommonsComponentProps, IDensityProps,
    IRoundedProps, ISizeProps, ITagProps, IColorProps, IPaddingProps,
    IMarginProps, IBorderProps, IStatusProps, IElevationProps,
    IHoverProps, IActiveProps, ITypographyProps {
    start?: boolean
    end?: boolean
    image?: string | ISrcObject
    text?: string
}

Typography props ​

PropTypeDefaultDescription
fontSizeTFontSize—Override the initials font-size. Maps to --origam-avatar---font-size via --origam-font__size---{value}.
fontWeightTFontWeight—Override the initials font-weight. Maps to --origam-avatar---font-weight via --origam-font__weight---{value}.
lineHeightTLineHeight—Override the avatar line-height. Maps to --origam-avatar---line-height via --origam-font__lineHeight---{value}.
letterSpacingTLetterSpacing—Override the initials letter-spacing. Maps to --origam-avatar---letter-spacing via --origam-font__letterSpacing---{value}.

Anatomy ​

html
<div class="origam-avatar origam-avatar--size-default
            origam-avatar--rounded origam-avatar--{status}">
    <div class="origam-avatar__wrapper">
        <div class="origam-avatar__image | origam-avatar__icon | origam-avatar__text">
            …
        </div>
    </div>
</div>

Design tokens consumed ​

CSS variablePurpose
--origam-avatar---width / --origam-avatar---heightAvatar bounding box.
--origam-avatar---densityDensity shaving (8px, 0px, 8px).
--origam-avatar---font-sizeInitials size — scales with size.
--origam-avatar---background / --origam-avatar---colorDefault chrome.
--origam-avatar---border-radiusDefaults to 50%. Overridden by rounded.
--origam-avatar---box-shadowEmpty by default, raised by elevation.
--origam-avatar--{intent}---background-colorPer-status background.
--origam-avatar--{intent}---colorPer-status foreground.

The full list lives in packages/ds/src/assets/css/tokens/light.css and dark.css (SCSS twins under packages/ds/src/assets/scss/tokens/) — grep for --origam-avatar---.

Accessibility ​

  • Provide a meaningful alt on the image source so AT users get a description rather than a generic "image" label.
  • For purely decorative avatars (e.g. group affordance), pass alt="" on the inner OrigamImg and rely on the host context for meaning.
  • Use the tag="button" polymorph when the avatar is interactive. Plain <div>s are not announced as actionable.

Theming notes ​

  • The avatar inherits the active theme automatically. Switching <html data-theme="dark"> re-resolves both default and status intents.
  • A nested <OrigamThemeProvider> re-skins a sub-tree without re-mounting components.
  • OrigamAvatarGroup — overlapping cluster with hover / click expand.
  • OrigamImg — underlying picture surface.
  • OrigamIcon — icon rendering when icon is set.