Avatar Badge for Wappler

Professional Avatar Badge and Avatar Group Web Components for Wappler with comprehensive features for displaying user profiles, status indicators, count badges, and avatar grouping.

Version 1.0.1

This release improves the Wappler App Connect inspector integration. Dynamic attributes now use Wappler's standard fieldset/group-enabler pattern, so the checkbox beside each dynamic property can enable or remove the generated dmx-bind: attribute correctly.

Features

Avatar Badge (<avatar-badge>)

• Image Support: Display user images with fallback to initials or icons
• Flexible Fallbacks: Automatic initials generation, custom initials, icon support, or custom HTML content
• Status Indicators: Show online/offline/away/busy status with customizable positions
• Count Badges: Display notification counts with configurable maximum and overflow indicator
• Auto-Color: Automatic color assignment based on user name/initials for consistent avatars
• Responsive Sizing: Predefined size tokens (xs, sm, md, lg, xl, xxl) or custom pixel sizes
• Multiple Shapes: Circle, rounded square, or square variants
• Bootstrap Integration: Works seamlessly with Bootstrap 5 color utilities
• Image Loading: Lazy loading support with fetchpriority control
• Accessible: Proper ARIA labels and semantic HTML
• Clickable: Optional link wrapper with target and rel support

Avatar Group (<avatar-group>)

• Stack Avatars: Display multiple avatars in an overlapping stack
• Overflow Display: Automatically show "+N" indicator for additional avatars beyond max count
• Configurable Spacing: Control the overlap amount
• Size Propagation: Automatically apply group size to child avatars

Installation

Install this extension directly from within Wappler using the Project Options > Extensions panel:

1. Open your project in Wappler.
2. Go to Project Options (the gear icon in the top toolbar).
3. Select the Extensions tab.
4. In the search box, type avatar-badge or @benpley/wappler-avatar-badge.
5. Locate Avatar Badge for Wappler in the results and click Add.
6. Wappler will install the extension and automatically copy the required CSS and JavaScript files to your project.

Note: The extension requires Wappler and is installed per-project. Make sure your project is open before installing.

Basic Usage

Simple Avatar with Image

<avatar-badge 
    src="/images/user.jpg" 
    name="John Smith"
    size="md">
</avatar-badge>

Avatar with Initials Fallback

<avatar-badge 
    name="Sarah Johnson"
    size="lg"
    auto-color>
</avatar-badge>

Avatar with Status Indicator

<avatar-badge 
    src="/images/user.jpg"
    name="Michael Brown"
    status="online"
    status-position="bottom-end">
</avatar-badge>

Avatar with Count Badge

<avatar-badge 
    src="/images/user.jpg"
    name="Emily Davis"
    count="5"
    count-max="9"
    count-position="top-end">
</avatar-badge>

Avatar with Icon Fallback

<avatar-badge 
    icon="fas fa-user"
    name="Guest User"
    bg="secondary"
    text="white">
</avatar-badge>

Clickable Avatar

<avatar-badge 
    src="/images/user.jpg"
    name="John Smith"
    href="/profile/123"
    size="lg">
</avatar-badge>

Avatar Group

<avatar-group max="4" size="md" spacing="-12px">
    <avatar-badge src="/images/user1.jpg" name="John Smith"></avatar-badge>
    <avatar-badge src="/images/user2.jpg" name="Sarah Johnson"></avatar-badge>
    <avatar-badge src="/images/user3.jpg" name="Michael Brown"></avatar-badge>
    <avatar-badge src="/images/user4.jpg" name="Emily Davis"></avatar-badge>
    <avatar-badge src="/images/user5.jpg" name="David Wilson"></avatar-badge>
    <avatar-badge src="/images/user6.jpg" name="Lisa Anderson"></avatar-badge>
</avatar-group>

Avatar Badge Attributes

Core Attributes

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | id | text | - | Unique identifier for the avatar | | name | text | - | User's full name (used for initials and ARIA labels) | | src | text | - | URL of the avatar image | | size | text | md | Size token: xs, sm, md, lg, xl, xxl |

Fallback Options

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | initials | text | - | Custom initials (overrides auto-generated from name) | | icon | text | - | Icon class (e.g., fas fa-user) to show instead of initials |

Appearance

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | shape | text | circle | Shape: circle, rounded, or square | | variant | text | - | Bootstrap variant: primary, secondary, etc. | | bg | text | primary | Background color (Bootstrap color class) | | text | text | white | Text color (Bootstrap color class) | | auto-color | boolean | false | Automatically assign colors based on name | | border | text | - | Border color (enable border by adding attribute) | | border-width | number | 2 | Border width in pixels (1-5) |

Status Indicator

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | status | text | - | Status: online, offline, away, busy or custom color | | status-position | text | bottom-end | Position: bottom-end, bottom-start, top-end, top-start |

Count Badge

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | count | number | - | Number to display in badge | | count-max | number | - | Maximum count before showing "N+" | | count-bg | text | danger | Badge background color | | count-text | text | white | Badge text color | | count-position | text | top-end | Badge position |

Image Loading

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | loading | text | lazy | Image loading: lazy, eager | | fetchpriority | text | - | Fetch priority: high, low, auto |

Link Wrapper

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | href | text | - | URL to link to | | target | text | - | Link target (e.g., _blank) | | rel | text | - | Link relationship |

Avatar Group Attributes

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | max | number | - | Maximum avatars to show before overflow indicator | | size | text | md | Size token applied to all child avatars: xs, sm, md, lg, xl, xxl | | spacing | text | -8px | Overlap spacing (negative for overlap) |

Size Tokens

Predefined size tokens for consistent sizing:

• xs = 24px
• sm = 32px
• md = 40px (default)
• lg = 56px
• xl = 80px
• xxl = 112px

Color Auto-Assignment

When auto-color attribute is present and no explicit bg or variant is set, the component automatically assigns a consistent color from a Bootstrap-friendly palette based on the user's name or initials. This ensures the same user always gets the same color.

App Connect Integration

The component is fully integrated with Wappler's App Connect framework:

Dynamic Attribute Support in Wappler

The extension exposes common avatar attributes in Wappler's Dynamic Attributes panel using Wappler's standard removable checkbox pattern. This allows dynamic bindings to be enabled, edited, or removed cleanly from the inspector.

Supported dynamic attributes:

• dmx-bind:src
• dmx-bind:name
• dmx-bind:status
• dmx-bind:count
• dmx-bind:href

In Wappler, select an <avatar-badge> element, expand Dynamic Attributes, enable the property checkbox, and choose the App Connect expression for the value. Disabling the checkbox removes the corresponding dmx-bind: attribute from the markup.

The attribute will now use dmx-bind: in the generated markup and react to data changes automatically.

Static (fixed value):

<avatar-badge
    src="/images/john.jpg"
    name="John Smith"
    status="online"
    size="md">
</avatar-badge>

Dynamic (bound to App Connect data):

<!-- After toggling each field to Dynamic Attribute in Wappler -->
<avatar-badge
    dmx-bind:src="user.avatar_url"
    dmx-bind:name="user.full_name"
    dmx-bind:status="user.online_status"
    size="md">
</avatar-badge>

Note: Static attributes (like size, auto-color, rounded) that only ever use preset tokens do not need to be toggled — set them directly as plain attributes.

Dynamic in a repeater:

<div dmx-repeat:user="users_list.data">
    <avatar-badge
        dmx-bind:src="avatar_url"
        dmx-bind:name="full_name"
        dmx-bind:status="online_status"
        size="sm"
        auto-color>
    </avatar-badge>
</div>

Dynamic Bindings

<avatar-badge 
    dmx-bind:src="user.avatar"
    dmx-bind:name="user.fullname"
    dmx-bind:status="user.online_status"
    dmx-bind:count="user.unread_messages">
</avatar-badge>

In Repeaters

<div dmx-repeat:users="users_list.data">
    <avatar-badge 
        dmx-bind:src="avatar_url"
        dmx-bind:name="full_name"
        dmx-bind:href="'/profile/' + id"
        auto-color>
    </avatar-badge>
</div>

With Conditions

<avatar-badge 
    src="/images/user.jpg"
    name="John Smith"
    dmx-bind:status="is_online ? 'online' : 'offline'"
    dmx-bind:count="unread_count">
</avatar-badge>

Accessibility

The component follows accessibility best practices:

• Proper ARIA labels for images and fallbacks
• Status indicators include ARIA labels
• Count badges include notification count in ARIA
• Decorative images (without name) are marked with empty alt and aria-hidden
• Semantic HTML structure

Browser Support

Works in all modern browsers that support:

• Custom Elements (Web Components)
• ES6+ JavaScript features

Customization

Custom Colors

Override Bootstrap color variables or add custom CSS classes:

<avatar-badge 
    name="Custom User"
    bg="custom-purple"
    text="white">
</avatar-badge>

.bg-custom-purple {
    background-color: #9b59b6 !important;
}

Custom Styles

The component uses scoped CSS classes that can be targeted:

avatar-badge .ab-wrap {
    /* Custom wrapper styles */
}

avatar-badge .ab-img {
    /* Custom image styles */
}

avatar-badge .ab-fallback {
    /* Custom fallback container styles */
}

Performance

• Lazy Loading: Images are lazy-loaded by default
• Efficient Rendering: Microtask-based batched rendering
• Memory Management: Proper cleanup on disconnect
• Minimal DOM: Efficient DOM structure
• CSS Variables: Hardware-accelerated CSS custom properties

License

MIT License - see LICENSE.md for details

Author

Ben Pleysier

Support

For issues, questions, or contributions:

• Wappler Community Forum: https://community.wappler.io

Changelog

1.0.1 (2026-05-07)

• Fixed Wappler Dynamic Attributes inspector behavior for custom App Connect attributes
• Reworked dynamic binding rules to use Wappler's fieldset/group-enabler pattern
• Added removable checkbox support for src, name, status, count, and href dynamic bindings
• Normalized components.hjson string values with quoted strings for reliable Wappler rule parsing
• Improved README documentation for Dynamic Attributes usage

1.0.0 (2026-04-27)

• Initial release
• Avatar Badge component with full feature set
• Avatar Group component for stacked avatars
• Bootstrap 5 integration
• App Connect integration
• Complete accessibility support