Skip to main content
Browse docs

Marwes documentation

Avatar

Canonical identity family with a base Avatar component, two scoped compositions, and thin semantic wrappers for profile, presence, and team contexts.

What this family solves

Canonical identity family with a base Avatar component, two scoped compositions, and thin semantic wrappers for profile, presence, and team contexts.

Use when

  • The UI needs a person or member identity surface with stable size, content-type, and semantic behavior.
  • The product flow maps clearly to ProfileAvatar, PresenceAvatar, or TeamAvatarGroup and benefits from canonical purpose metadata.
  • The team wants React and Vue avatar behavior to stay aligned through shared contracts and the central semantic registry.

Avoid when

  • The surface really needs an interactive profile menu, upload flow, or editable identity control rather than a static avatar family member.
  • The implementation cannot provide truthful alt text or aria labeling for a non-decorative identity surface.
  • The team expects avatar-group layouts beyond the current stacked medium pattern and overflow counter defined by the shipped family.

Public imports

Choose an adapter in the verified examples. The inventory below reflects each framework package exactly.

React — @marwes-ui/react

Components

Avatar, AvatarBadge, AvatarGroup, PresenceAvatar, ProfileAvatar, TeamAvatarGroup

Types

AvatarBadgeProps, AvatarGroupItem, AvatarGroupProps, AvatarProps, PresenceAvatarProps, ProfileAvatarProps, TeamAvatarGroupProps

Enums

AvatarSize, AvatarType

Vue — @marwes-ui/vue

Components

Avatar, AvatarBadge, AvatarGroup, PresenceAvatar, ProfileAvatar, TeamAvatarGroup

Types

AvatarBadgeProps, AvatarGroupItem, AvatarGroupProps, AvatarProps, PresenceAvatarProps, ProfileAvatarProps, TeamAvatarGroupProps

Enums

AvatarSize, AvatarType

Svelte — @marwes-ui/svelte

Components

Avatar, AvatarBadge, AvatarGroup, PresenceAvatar, ProfileAvatar, TeamAvatarGroup

Types

AvatarBadgeProps, AvatarGroupItem, AvatarGroupProps, AvatarProps, PresenceAvatarProps, ProfileAvatarProps, TeamAvatarGroupProps

Enums

AvatarSize, AvatarType

Verified minimal examples

These examples come from the same fixtures verified by the repository checks.

React

import { Avatar, AvatarBadge, AvatarGroup } from "@marwes-ui/react"

export function Example() {
  return (
    <>
      <AvatarGroup
        items={[
          { initials: "MO" },
          { initials: "MO" },
          { initials: "MO" },
          { type: "icon", label: "Guest member" },
        ]}
        overflowCount={3}
      />
      <AvatarBadge initials="MO" statusLabel="Online" />
      <Avatar src="/avatar.png" alt="User" />
      <Avatar initials="MO" size="small" />
      <Avatar type="icon" label="User icon fallback" />
    </>
  )
}

Vue

<script setup lang="ts">
import { Avatar, AvatarBadge, AvatarGroup } from "@marwes-ui/vue"
</script>

<template>
  <AvatarGroup
    :items="[
      { initials: 'MO' },
      { initials: 'MO' },
      { initials: 'MO' },
      { type: 'icon', label: 'Guest member' },
    ]"
    :overflow-count="3"
  />
  <AvatarBadge initials="MO" status-label="Online" />
  <Avatar src="/avatar.png" alt="User" />
  <Avatar initials="MO" size="small" />
  <Avatar type="icon" label="User icon fallback" />
</template>

Svelte

<script lang="ts">
  import { Avatar, AvatarBadge, AvatarGroup } from "@marwes-ui/svelte"
</script>

<AvatarGroup
  items={[
    { initials: "MO" },
    { initials: "MO" },
    { initials: "MO" },
    { type: "icon", label: "Guest member" },
  ]}
  overflowCount={3}
/>
<AvatarBadge initials="MO" statusLabel="Online" />
<Avatar src="/avatar.png" alt="User" />
<Avatar initials="MO" size="small" />
<Avatar type="icon" label="User icon fallback" />

Accessibility requirements

  • Truthful alt text: Provide real alt text for photographic avatars and mark decorative fallbacks appropriately.
  • Status labeling: Give every status indicator on AvatarBadge a truthful statusLabel, not just a colored dot.
  • Manual review boundary: Product-level quality of alt text, aria labels, status labels, and overflow wording.
  • Manual review 2: Dev-time warning for image avatars without alt or ariaLabel is now implemented in avatar-a11y.ts.
  • Manual review 3: Any future expansion beyond the current non-interactive avatar, badge, and group scope.

Theming

Avatar uses Marwes preset CSS and theme variables. Customize it through the theme passed to MarwesProvider; do not add a second component stylesheet. See the theming guide for configuration and token details.

Resources