🎲 DiceBear Avatar - Wappler App Connect Extension

Generate beautiful, customizable avatars dynamically using the DiceBear API! Perfect for user profiles, comments, chat applications, and any interface that needs unique, visually appealing avatars.

✨ Features

• 🎨 27 Different Avatar Styles - From cute to professional
• 🔗 Dynamic Data Binding - Bind seed to username, email, user ID, etc.
• 📐 Fully Customizable - Size, colors, formats, borders
• ⚡ Loading States - Built-in spinner and error handling
• 🎯 Click Events - Interactive avatars with custom events
• 🎲 Randomization - Generate random avatars on demand
• 🔄 Transform Options - Flip and rotate
• 💾 Download Support - Save avatars locally
• 📋 Copy URL - One-click URL copying
• 🎭 Multiple Formats - SVG, PNG, JPG, WEBP

🎨 Available Avatar Styles

| Style | Description | Best For | |-------|-------------|----------| | avataaars | Sketch-style cartoon avatars | General purpose, professional | | adventurer | Adventurous characters | Fun, gaming | | big-ears | Cute characters with big ears | Friendly apps | | big-smile | Happy, smiling faces | Positive vibes | | bottts | Robot avatars | Tech, sci-fi | | croodles | Doodle-style avatars | Creative, artistic | | fun-emoji | Emoji-based avatars | Casual, fun | | icons | Abstract icon designs | Modern, minimal | | identicon | Geometric patterns | Technical, unique | | initials | Text-based initials | Professional, simple | | lorelei | Illustrated portraits | Elegant, personal | | micah | Diverse character set | Inclusive, varied | | miniavs | Minimalist avatars | Clean, simple | | notionists | Notion-style avatars | Professional, modern | | open-peeps | Open Peeps library | Diverse, inclusive | | personas | Persona illustrations | Business, professional | | pixel-art | 8-bit pixel style | Retro, gaming | | rings | Abstract ring patterns | Modern, unique | | shapes | Geometric shapes | Abstract, minimal | | thumbs | Thumbs up/down | Feedback, voting |

📦 Installation

Step 1: Install via NPM

cd /path/to/your/wappler/project
npm install wappler-dicebear-avatar

Step 2: Copy JavaScript File

cp node_modules/wappler-dicebear-avatar/dmx-dicebear-avatar.js public/js/

Step 3: Register in Wappler Project

Edit .wappler/project.json and add to extensions:

{
  "extensions": [
    {
      "name": "wappler-dicebear-avatar"
    }
  ]
}

Step 4: Restart Wappler

Completely quit and reopen Wappler.

Alternative: Local Development Install

For local development:

# Clone or link the package
cd ~/wappler-extensions/dicebear-avatar
npm link

# Link to your project
cd /path/to/your/wappler/project
npm link wappler-dicebear-avatar

# Copy JS file
cp node_modules/wappler-dicebear-avatar/dmx-dicebear-avatar.js public/js/

🚀 Quick Start

Basic Usage

<dmx-dicebear-avatar 
  id="avatar1" 
  seed="JohnDoe"
  style="avataaars"
  size="200">
</dmx-dicebear-avatar>

With Data Binding

<dmx-dicebear-avatar 
  id="userAvatar" 
  dmx-bind:seed="user.username"
  style="lorelei"
  size="150"
  radius="50">
</dmx-dicebear-avatar>

Full Configuration

<dmx-dicebear-avatar 
  id="avatar2"
  seed="Alice123"
  style="pixel-art"
  size="300"
  radius="16"
  background-color="e0e0e0"
  format="svg"
  flip="false"
  rotate="0"
  clickable="true"
  show-loading="true"
  dmx-on:clicked="console.log('Avatar clicked!')">
</dmx-dicebear-avatar>

⚙️ Component Properties

Basic Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | id | String | 'avatar1' | Unique component ID | | seed | String | 'Wappler' | Seed value for avatar (supports data binding) | | style | Dropdown | 'avataaars' | Avatar art style (27 options) |

Image Settings

| Property | Type | Default | Description | |----------|------|---------|-------------| | size | Number | 200 | Avatar size in pixels | | radius | Dropdown | '0' | Border radius (0, 8, 16, 32, 50) | | background-color | String | 'transparent' | Background color (hex without #) | | format | Dropdown | 'svg' | Image format (svg, png, jpg, webp) |

Display Options

| Property | Type | Default | Description | |----------|------|---------|-------------| | alt | String | 'Avatar' | Alt text for accessibility | | css-class | String | '' | Additional CSS classes | | show-loading | Boolean | true | Show loading spinner | | clickable | Boolean | true | Enable click interactions |

Advanced Options

| Property | Type | Default | Description | |----------|------|---------|-------------| | flip | Boolean | false | Horizontally flip avatar | | rotate | Dropdown | '0' | Rotation (0, 90, 180, 270) | | randomize | Boolean | false | Randomize on load | | cache | Boolean | true | Enable browser caching |

📊 Data Output

The component exposes reactive data:

| Property | Type | Description | |----------|------|-------------| | seed | String | Current seed value | | style | String | Current style | | url | String | Generated DiceBear URL | | isLoaded | Boolean | Image loaded successfully | | error | String | Error message (if any) |

Accessing Data

<!-- Display avatar URL -->
<p>URL: {{avatar1.url}}</p>

<!-- Display seed -->
<p>Seed: {{avatar1.seed}}</p>

<!-- Check if loaded -->
<p>Loaded: {{avatar1.isLoaded}}</p>

🎪 Custom Events

Core Events

clicked

Fired when avatar is clicked.

<dmx-dicebear-avatar 
  id="avatar1"
  dmx-on:clicked="console.log('Clicked!', $event.seed)">
</dmx-dicebear-avatar>

Payload: { seed, style, url, clickCount }

loaded

Fired when image loads successfully.

<dmx-dicebear-avatar 
  id="avatar1"
  dmx-on:loaded="notify.success('Avatar loaded!')">
</dmx-dicebear-avatar>

Payload: { url, seed, style }

error

Fired when image fails to load.

<dmx-dicebear-avatar 
  id="avatar1"
  dmx-on:error="notify.error('Failed to load avatar')">
</dmx-dicebear-avatar>

Payload: { error, url }

Data Change Events

seedChanged

Fired when seed value changes.

Payload: { oldSeed, newSeed }

styleChanged

Fired when style changes.

Payload: { oldStyle, newStyle }

Action Events

randomized

Fired when avatar is randomized.

Payload: { seed, url }

refreshed

Fired when avatar is refreshed.

Payload: { url, timestamp }

downloaded

Fired when avatar is downloaded.

Payload: { filename, url }

urlCopied

Fired when URL is copied to clipboard.

Payload: { url }

mounted / destroyed

Lifecycle events.

🔧 Public Methods

setSeed(newSeed)

Update the seed value.

<button dmx-on:click="avatar1.setSeed('NewUser123')">
  Change Avatar
</button>

setStyle(newStyle)

Change the avatar style.

<button dmx-on:click="avatar1.setStyle('pixel-art')">
  Pixel Art Style
</button>

randomize()

Generate a random avatar.

<button dmx-on:click="avatar1.randomize()">
  🎲 Random Avatar
</button>

refresh()

Refresh/reload the avatar.

<button dmx-on:click="avatar1.refresh()">
  🔄 Refresh
</button>

downloadAvatar(filename)

Download the avatar image.

<button dmx-on:click="avatar1.downloadAvatar('my-avatar.svg')">
  💾 Download
</button>

copyUrl()

Copy avatar URL to clipboard.

<button dmx-on:click="avatar1.copyUrl()">
  📋 Copy URL
</button>

getUrl() / getSeed() / getStyle()

Get current values.

<p dmx-text="avatar1.getUrl()"></p>

getState()

Get complete component state.

<button dmx-on:click="console.log(avatar1.getState())">
  Show State
</button>

🎨 Usage Examples

Example 1: User Profile Avatar

<!-- Bind to user data -->
<dmx-dicebear-avatar 
  id="profileAvatar"
  dmx-bind:seed="user.email"
  style="lorelei"
  size="200"
  radius="50"
  clickable="false">
</dmx-dicebear-avatar>

<h3 dmx-text="user.name"></h3>
<p dmx-text="user.email"></p>

Example 2: Comment System

<!-- Loop through comments -->
<div dmx-repeat:comment="comments.data">
  <div class="comment">
    <dmx-dicebear-avatar 
      id="avatar_{{comment.id}}"
      dmx-bind:seed="comment.author"
      style="avataaars"
      size="50"
      radius="50">
    </dmx-dicebear-avatar>
    <div class="comment-content">
      <strong dmx-text="comment.author"></strong>
      <p dmx-text="comment.text"></p>
    </div>
  </div>
</div>

Example 3: Avatar Generator

<!-- Interactive avatar creator -->
<div class="avatar-generator">
  <dmx-dicebear-avatar 
    id="generator"
    seed="Preview"
    style="avataaars"
    size="300"
    radius="16">
  </dmx-dicebear-avatar>
  
  <input type="text" id="seedInput" placeholder="Enter seed">
  
  <button dmx-on:click="generator.setSeed(seedInput.value)">
    Update Avatar
  </button>
  
  <button dmx-on:click="generator.randomize()">
    🎲 Random
  </button>
  
  <button dmx-on:click="generator.downloadAvatar()">
    💾 Download
  </button>
  
  <button dmx-on:click="generator.copyUrl()">
    📋 Copy URL
  </button>
  
  <p>URL: {{generator.url}}</p>
</div>

Example 4: Style Selector

<dmx-dicebear-avatar 
  id="stylePicker"
  seed="StyleDemo"
  size="200">
</dmx-dicebear-avatar>

<select id="styleSelect">
  <option value="avataaars">Avataaars</option>
  <option value="pixel-art">Pixel Art</option>
  <option value="bottts">Bottts</option>
  <option value="lorelei">Lorelei</option>
</select>

<button dmx-on:click="stylePicker.setStyle(styleSelect.value)">
  Change Style
</button>

Example 5: Chat Application

<!-- Chat messages -->
<div dmx-repeat:message="chat.messages">
  <div class="message">
    <dmx-dicebear-avatar 
      id="msg_{{message.id}}"
      dmx-bind:seed="message.userId"
      style="big-smile"
      size="40"
      radius="50">
    </dmx-dicebear-avatar>
    <div class="message-bubble">
      <strong dmx-text="message.username"></strong>
      <p dmx-text="message.text"></p>
    </div>
  </div>
</div>

🎯 Advanced Tips

Dynamic Styling

Add custom CSS classes for effects:

<dmx-dicebear-avatar 
  id="avatar1"
  css-class="shadow-lg hover-lift"
  size="200">
</dmx-dicebear-avatar>

<style>
.shadow-lg {
  box-shadow: 0 10px 30px rgba(0,0,0,0.3);
}
.hover-lift:hover {
  transform: translateY(-5px);
}
</style>

Responsive Sizes

Use data binding for responsive avatars:

<dmx-dicebear-avatar 
  id="responsive"
  dmx-bind:size="browser.width < 768 ? 80 : 150">
</dmx-dicebear-avatar>

Conditional Randomization

<dmx-dicebear-avatar 
  id="conditional"
  dmx-bind:randomize="user.isNew == true">
</dmx-dicebear-avatar>

🌐 DiceBear API

This component uses the official DiceBear API:

• Base URL: https://api.dicebear.com/9.x/
• Documentation: https://www.dicebear.com/
• Free to use with attribution

🐛 Troubleshooting

Avatar Not Loading?

1. Check browser console for errors
2. Verify internet connection
3. Check if seed value is valid
4. Try a different style

Component Not Showing in Wappler?

1. Verify package is linked: npm list @custom/wappler-dicebear-avatar
2. Check JS file is in public/js/
3. Confirm extension in .wappler/project.json
4. Restart Wappler completely

📄 License

MIT License - Free to use in your projects!

🎉 Credits

• DiceBear - Avatar API (https://dicebear.com)
• Wappler - Low-code platform
• Component Design - Custom Extensions

Ready to generate amazing avatars! 🎲✨

Start using it in your Wappler projects today!