ReferenceWidgets
Buddy widget
The animated companion — shows evolution stage, equipped items, and reacts to live events.
The buddy widget is the centerpiece. It shows the current evolution stage, equipped marketplace items, and plays animations when coins are earned, badges awarded, or evolution becomes available.
Mount
<div
data-hatched-widget="buddy"
data-hatched-token="SESSION_OR_EMBED_TOKEN"
data-hatched-size="md"
data-hatched-theme="auto"
></div>Attributes
| Attribute | Values | Default | Notes |
|---|---|---|---|
data-hatched-token | session or embed token | — | required |
data-hatched-size | sm md lg full | md | full fills the container |
data-hatched-theme | light dark auto | auto | |
data-hatched-accent | #RRGGBB | brand | per-page override |
data-hatched-controls | minimal full | full | minimal hides the action row |
data-hatched-autoplay | true false | true | Ambient animations |
Required scopes
buddy:read— to renderbuddy:interact— to enable the action row (feed, pet, evolve)
Events (DOM CustomEvents)
The element emits native DOM events you can listen to:
const el = document.querySelector('[data-hatched-widget="buddy"]');
el.addEventListener('hatched:ready', (e) => {
console.log('buddy mounted', e.detail.buddyId);
});
el.addEventListener('hatched:coin-earned', (e) => {
console.log('+', e.detail.amount, 'coins');
});
el.addEventListener('hatched:evolution-ready', (e) => {
showEvolvePromo(e.detail.nextStage);
});Full event list: ready, error, coin-earned, badge-awarded,
streak-ticked, evolution-ready, item-equipped.
Embedding read-only
For anonymous marketing pages or listings, skip session minting and use an embed token instead:
const { token } = await hatched.eggs.embedToken(buddyId, {
ttlSeconds: 60 * 60,
});Embed tokens can't trigger interactions (feed, evolve, equip).