Skip to content

Avatar

Circular avatar displaying an image, initials, or icon fallback. Supports four sizes and an optional status dot indicator.

import { Avatar } from "phoundry-ui";

With Image

Loading interactive example…

View source
with-image.svelte
<script lang="ts">
import { Avatar } from "phoundry-ui";
</script>
<Avatar src="https://i.pravatar.cc/80?u=1" alt="Jane Doe" />

Initials

Loading interactive example…

View source
initials.svelte
<script lang="ts">
import { Avatar } from "phoundry-ui";
</script>
<div class="flex items-center gap-3">
<Avatar initials="JD" />
<Avatar initials="AB" />
<Avatar initials="XY" />
</div>

Icon Fallback

Loading interactive example…

View source
icon-fallback.svelte
<script lang="ts">
import { Avatar } from "phoundry-ui";
import { PhiIcons } from "phoundry-ui";
</script>
<p class="mb-2 text-xs text-txt-secondary">
Use any Iconify id or shared tokens from <code>PhiIcons</code> when there is no
photo or initials.
</p>
<div class="flex items-center gap-3">
<Avatar icon={PhiIcons.folder} />
<Avatar icon={PhiIcons.document} />
</div>

Image with status

Loading interactive example…

View source
image-with-status.svelte
<script lang="ts">
import { Avatar } from "phoundry-ui";
</script>
<div class="flex items-center gap-3">
<Avatar
src="https://i.pravatar.cc/80?u=7"
alt="Team member"
status="online"
size="md"
/>
<Avatar
src="https://i.pravatar.cc/80?u=8"
alt="Away user"
status="away"
size="sm"
/>
</div>

Default user glyph

Loading interactive example…

View source
default-user-glyph.svelte
<script lang="ts">
import { Avatar } from "phoundry-ui";
</script>
<div class="flex items-center gap-3">
<Avatar size="sm" />
<Avatar size="md" />
</div>

Sizes

Loading interactive example…

View source
sizes.svelte
<script lang="ts">
import { Avatar } from "phoundry-ui";
</script>
<div class="flex items-center gap-3">
<Avatar initials="XS" size="xs" />
<Avatar initials="SM" size="sm" />
<Avatar initials="MD" size="md" />
<Avatar initials="LG" size="lg" />
</div>

Status Indicators

Loading interactive example…

View source
status-indicators.svelte
<script lang="ts">
import { Avatar } from "phoundry-ui";
</script>
<div class="flex items-center gap-3">
<Avatar initials="ON" status="online" />
<Avatar initials="AW" status="away" />
<Avatar initials="BS" status="busy" />
<Avatar initials="OF" status="offline" />
</div>

API

From phoundry-ui@0.4.21

NameTypeDefaultDescription
srcstring—Image URL for the avatar.
altstring''Alt text for the image.
initialsstring—Initials to display when no image is provided.
iconstring—Iconify icon string used as fallback when no image or initials.
size"xs" | "sm" | "md" | "lg"'md'Avatar size.
status"online" | "offline" | "away" | "busy"—Status dot indicator.
classClassValue—Additional CSS classes.
stylestring—Inline styles on the stable component root.

Usage tips

  • The avatar falls back gracefully: image → initials → explicit icon → default user icon.
  • If the image fails to load, the component automatically switches to the initials or icon fallback.
  • Provide meaningful alt text whenever src is set; it defaults to an empty string.
  • Use status alongside user avatars in chat, team lists, or collaboration UIs.

Styling

.ph-avatar is the stable root hook. Consumer class values are additive, and style applies to that root. Styling uses vanilla CSS with semantic state attributes. Avatar intentionally retains its own scale: xs 1.5rem, sm 2rem, md 2.5rem, and lg 3.5rem. It does not consume the shared control-height tokens. Its initials, icon, and status-dot dimensions retain their previous proportions. The root emits data-size; the status part emits data-status. Image, initials, explicit icon, and default-user fallback precedence is unchanged. Internal part selectors and --_ph-* properties remain implementation details.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.