Avatar
User avatars with image support and initials fallback. Includes status indicators and custom color options.
When to Use
Use Avatar when:
Representing a user or team member in navigation bars, comments, participant lists, or user profiles. The initials fallback ensures a consistent look even without a photo.
Don't use when:
Displaying a generic icon or logo — use an icon or image instead. For decorative thumbnails unrelated to a person, use a standard image element.
Sizes
AB
BS
CW
DL
EJ
<?= ws_avatar('Alice Brown', ['size' => 'xs']) ?>
<?= ws_avatar('Bob Smith', ['size' => 'sm']) ?>
<?= ws_avatar('Carol White', ['size' => 'md']) ?>
<?= ws_avatar('David Lee', ['size' => 'lg']) ?>
<?= ws_avatar('Eve Johnson', ['size' => 'xl']) ?>With Images
When an image URL is provided, it replaces the initials fallback.
<?= ws_avatar('John Doe', ['image' => '/path/to/avatar.jpg']) ?>With Status
A coloured dot indicates online, offline, or busy status.
OU
OU
BU
<?= ws_avatar('User', ['status' => 'online']) ?>
<?= ws_avatar('User', ['status' => 'offline']) ?>
<?= ws_avatar('User', ['status' => 'busy']) ?>Custom Colors
Override the default background colour for initials avatars. Useful for colour-coding by role or team.
PU
CU
RU
<?= ws_avatar('Plan User', ['color' => '#0284C7']) ?>With Ring
RI
<?= ws_avatar('User', ['ring' => true]) ?>Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
$name | string | — | User name (used for initials fallback and title) |
image | string | null | Image URL |
size | string | md | xs | sm | md | lg | xl |
color | string | null | Custom background colour (hex) for initials |
ring | bool | false | Show focus/highlight ring |
status | string | null | online | offline | busy |
id | string | null | Element ID |
class | string | '' | Additional CSS classes |
attrs | array | [] | Extra HTML attributes |
Anatomy
.ws-avatar — Outer container <div>.ws-avatar__image — <img> element (when image provided).ws-avatar__initials — Initials text (fallback).ws-avatar__status — Status indicator dotCSS Classes
| Class | Purpose |
|---|---|
.ws-avatar | Base avatar styles |
.ws-avatar--xs / --sm / --md / --lg / --xl | Size modifiers |
.ws-avatar--initials | Applied when showing initials (no image) |
.ws-avatar--ring | Focus/highlight ring |
.ws-avatar__status--online | Green status dot |
.ws-avatar__status--offline | Grey status dot |
.ws-avatar__status--busy | Red status dot |
.ws-avatar-group | Overlapping avatar stack |
Files
| File | Purpose |
|---|---|
includes/components/helpers.php | ws_avatar() helper function |
includes/components/avatar.php | Avatar template |
includes/components/components.css | Avatar CSS (.ws-avatar rules) |