━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ SETUP — 3 STEPS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Install the plugin and drag the "Alphabet Avatar Pro" element onto your page.

2. In the element's Appearance tab, set "target_text" to any text field — typically a User's name, a Contact's name, or an Input's value.

3. Use the exposed state "current image" (avatar_url) as the source for any Image element on your page.

That's it. The avatar renders automatically whenever the name changes.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FIELDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

target_text — The name to generate the avatar from. Uses the first letter, or first + last initials if "Use Two Initials" is checked. Spaces and special characters are handled automatically.

Size — Avatar size in pixels. Accepts any value from 16 to 512. Default: 64. The canvas automatically scales for HiDPI / Retina screens.

Shape — Choose from: circle, square, or rounded (rounded square). Default: circle.

Background Color — Enter a hex color (e.g. #E53935) or leave as "random" to use a deterministic color seeded from the name. The same name will always produce the same color.

Font Color — Enter a hex color for the initials text. Leave blank to use automatic contrast (white on dark backgrounds, dark on light backgrounds).

font_weight — Controls the weight of the initials text. Options: normal (400), bold (700), black (900). Default: bold.

Use Two Initials — When checked, uses the first letter of the first word and first letter of the last word. "John Doe" becomes "JD". When unchecked, uses only the first letter.

border width — Adds a border around the avatar shape. Set to 0 for no border. Works with all shapes.

border color — Color of the border. Accepts hex values.

Drop Shadow — Adds a soft drop shadow beneath the avatar.

Font Size % — Controls the size of the initials text as a percentage of the total avatar size. Default: 40. Accepts 10–80. Connect a Slider element for live preview.

uppercase — Forces initials to uppercase. Default: on.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXPOSED STATES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

current image (avatar_url) — A PNG data URL of the rendered avatar. Use this as the source of any Bubble Image element. Can also be stored in the database or sent via API.

initials — The extracted initials as plain text (e.g. "JD"). Useful for displaying text overlays or logging.

svg_string — The full SVG markup of the avatar. Use this for email templates, PDF generation, or any context where a vector format is preferred.

background color used — The resolved hex color used as the background. Useful when using "random" mode — store this value so the color stays consistent when you save to the database.

text color used — The resolved hex color used for the initials text (either your custom color or the auto-contrast result).

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EVENTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

avatar_rendered — Fires each time the avatar successfully renders. Use this as a workflow trigger to save the avatar URL to your database, show a success message, or chain other actions.

render_failed — Fires if the render encounters an error. Use this to show a fallback or log the issue.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMMON USE CASES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

User profile avatars — Show a generated avatar when a user has not uploaded a profile photo. Use a Bubble condition: when "Profile Photo is empty", show Alphabet Avatar Pro 's current image instead.

Saving to database — On the "avatar_rendered" event, run a workflow: "Make changes to User → Profile Avatar = AlphabetImagePro's current image". This saves the data URL so you don't need to re-render on every page load.

Repeating Groups — Place the element inside a Repeating Group cell. Set target_text to "Current Cell's User's name". Each cell will render its own avatar automatically.

Email templates — Use the svg_string state to embed a vector avatar directly into SendGrid or Postmark HTML email templates.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TIPS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- Set the element width and height to match your Size field value for pixel-perfect layout.
- The element itself renders the canvas inline — you can use it directly as a visible element OR hide it and only use the exposed states.
- "random" background color is deterministic — the same name always gets the same color, so avatars look intentional even without manual color assignments.
- For Retina/HiDPI screens the canvas automatically renders at 2x resolution — your avatars will look sharp on all devices.
- Font Size % of 38–42 works best for most use cases. Go higher for a bolder, more modern look.