Web Component Usage

@avatar-generator/web-component ships a standards-based custom element, so you can drop an avatar into any HTML page with no framework. It works equally well inside React, Vue, Svelte, Solid, or anything else that can set a DOM property.

Installation

pnpm add @avatar-generator/core @avatar-generator/web-component @avatar-generator/style-initials

Basic usage

Importing the package auto-registers <avatar-generator>. Set the JavaScript properties styleImpl and options on the element:

import "@avatar-generator/web-component";
import { initials } from "@avatar-generator/style-initials";

const el = document.createElement("avatar-generator");
el.styleImpl = initials;
el.options = { seed: "Hugo GB", size: 64 };
el.setAttribute("alt", "Hugo GB");
document.body.append(el);

Why `styleImpl` and not `style`

Every HTMLElement already has a style property for inline CSS. Overriding it would break the platform, so the avatar style goes on styleImpl. Both it and options must be set as JS properties, not attributes — a Style is an object, and objects do not survive stringification into an attribute.

Setting styleImpl or options triggers an immediate re-render. Nothing renders until both are set.

In a plain HTML page

<script type="module">
    import "@avatar-generator/web-component";
    import { initials } from "@avatar-generator/style-initials";

    customElements.whenDefined("avatar-generator").then(() => {
        const el = document.querySelector("avatar-generator");
        el.styleImpl = initials;
        el.options = { seed: "Hugo GB", size: 64 };
    });
</script>

<avatar-generator alt="Hugo GB"></avatar-generator>

Custom tag name

If <avatar-generator> collides with something in your app, register the element under another name:

import { register } from "@avatar-generator/web-component";
import { initials } from "@avatar-generator/style-initials";

register("my-avatar");

const el = document.createElement("my-avatar");
el.styleImpl = initials;
el.options = { seed: "Hugo GB" };
document.body.append(el);

The extra name is registered alongside <avatar-generator>, not instead of it, and register is safe to call more than once — a name that already exists is ignored.

Fixed in v3

register(tagName) could never succeed before v3. Importing the package binds AvatarElement to <avatar-generator>, and the registry allows one tag name per constructor, so any custom name threw NotSupportedError. Additional names now get their own subclass.

Properties and attributes

Name	Kind	Default	Description
styleImpl	property	(required)	The avatar Style object — must be set as a JS property
options	property	(required)	Avatar options for that style — must be set as a JS property
alt	attribute	"Avatar"	Alt text for the internal <img>

Styling

The element renders its <img> inside an open shadow root, so page CSS does not reach inside it. Size and position the host element itself:

avatar-generator {
    display: inline-block;
    border-radius: 50%;
    overflow: hidden;
}

The shadow root is open, so el.shadowRoot is reachable if you need the <img> directly.

Server-side rendering

Importing this package during a server render is a no-op: the element extends a stand-in when there is no DOM, and register() returns early when there is no custom element registry. Importing it from a Next.js, Nuxt, Astro or SvelteKit server component is safe, and the element upgrades in the browser as usual.

Fixed in v3

In v2 this package threw ReferenceError: HTMLElement is not defined the moment it was imported on a server — before any of your own code ran. If you hit that, upgrade; see the Migration Guide.

There is no declarative shadow DOM output, so the avatar itself appears on the client. If you need the avatar in the server-rendered HTML, call createAvatar directly and inline avatar.svg — see the SSR recipe in the Cookbook.