Host SDK overview
The <togenar-embed> element is the SDK. There is no separate client library to load.
However you installed the element (script tag or npm i @togenar/embed),
you already have it. It exposes three surfaces:
1. Synchronous reads (cached)
Section titled “1. Synchronous reads (cached)”getSelection(), getSkus() and getShareUrl() return instantly from the last
selection_change event, with no round-trip. They return null / [] until the first event
arrives, so gate any UI on the event first:
tg.addEventListener('togenar:configurator:selection_change', () => { console.log(tg.getSkus()); // ["OSLO-BODY-WALNUT", "OSLO-LEGS-CHROME"] console.log(tg.getShareUrl()); // deep link that rebuilds this exact configuration});2. Async requests (Promise-based)
Section titled “2. Async requests (Promise-based)”Everything else (getOptions(), select(), setPrices(), enterAR(), …) round-trips
to the viewer and returns a Promise. Full list: Methods reference.
const { ok } = await tg.select('body', 'walnut'); // resolves AFTER the swap settlesYou can call these immediately, even before the viewer finishes loading. Requests are queued and flushed once the viewer’s bridge is up, so you never have to wait for a ready event before wiring your page. Requests time out after 30 s if the viewer never becomes reachable.
3. DOM events
Section titled “3. DOM events”The viewer reports back through bubbling togenar:* CustomEvents on the element, such as
togenar:ready and togenar:configurator:selection_change. Full list:
Events reference.
TypeScript
Section titled “TypeScript”@togenar/embed ships its own definitions, with nothing to install separately. Query the
element and every method is typed, including the shape of what it resolves to:
import '@togenar/embed';import type { TogenarEmbed, TogenarSelection } from '@togenar/embed';
const tg = document.querySelector<TogenarEmbed>('#tg')!;
const { selection } = await tg.select('body', 'walnut');selection.parts.forEach((p) => console.log(p.sku)); // typed
tg.addEventListener('togenar:configurator:selection_change', (e) => { const next: TogenarSelection = e.detail; // typed via HTMLElementEventMap});Attributes are typed in JSX too, so <togenar-embed project="…" configurator /> autocompletes
in React without a // @ts-ignore.
Security model
Section titled “Security model”- The embed only accepts messages from its own iframe and verifies the frame’s origin.
- Requests/responses are correlated by ID, so stray or duplicate messages are ignored.
- Removing the element from the DOM rejects all in-flight requests and tears the channel down cleanly.
