Embeds

Free read-only boards and the premium embeddable builder.

Which embed?

Embed	What it shows	Needs
`TieroBoard`	A read-only board, rendered on your server (good for SEO)	Nothing
Board frame	A read-only board in an iframe that sizes itself	Nothing
Builder frame	The full drag-and-drop builder, saving to the visitor's tiero account	Premium and an embed config

All three come from the @tiero/embed package. Every board carries a "Powered by tiero.io" credit; see Branding.

Install

pnpm add @tiero/embed svelte

Free boards

TieroBoard renders a list or consensus board during server rendering. Pass the DTO as board; optional props are size, showNames, poweredBy, ref, footer and credits.

Svelte, server rendered

<script>
  import { TieroBoard } from '@tiero/embed';
  let { data } = $props(); // data.consensus from createTieroClient().getConsensus('owner/slug')
</script>

<TieroBoard board={data.consensus} />

TieroBoardFrame needs no config: it uses the public embed, shows a catalog's consensus or one list (listId wins over catalog) and follows the board's height. theme is auto, light or dark.

Svelte, iframe

<script>
  import { TieroBoardFrame } from '@tiero/embed';
</script>

<TieroBoardFrame catalog="owner/slug" />
<TieroBoardFrame catalog="owner/slug" listId="YOUR_LIST_ID" theme="dark" />

Premium builder

With a premium account, create an embed at Account, Embeds. Each embed has:

a name (shown to visitors when they connect) and a mode, builder or board;
1 to 5 allowed origins: https://host[:port] or https://*.host, plus http://localhost:<port> and http://127.0.0.1:<port> for development;
the catalogs it may open, a theme (mode, accent, radius 0 to 16);
an optional list URL template containing {id}, on an allowed origin, for links to saved lists on your site.

Drop in the loader script, or use the Svelte component:

HTML

<div data-tiero-embed="emb_..." data-catalog="owner/slug"></div>
<script async src="https://tiero.io/embed.js"></script>

Svelte

<script>
  import { TieroBuilderFrame } from '@tiero/embed';
</script>

<TieroBuilderFrame
  embedId="emb_..."
  catalog="owner/slug"
  onsaved={({ listId, url }) => console.log('saved', listId, url)}
/>

The frame only renders on an allowed origin. An unknown or disabled embed, a catalog outside the list or a wrong origin shows an error card instead. If the owner's premium lapses, the builder falls back to a read-only board with a link to the builder on tiero.io. Add data-theme (or the theme prop) to override the configured theme mode.

Saving lists

Visitors save lists to their own tiero account. The first time, "Sign in to save" opens a small tiero.io window where they sign in and approve your embed by name, owner and origin. The frame then holds an embed token for that visitor; your page never sees it. Visitors can disconnect your site at any time from Account, Connected sites.

Lists saved from an embed are tagged with it, so you can show them with GET /api/v1/lists?embed=emb_....

Events

The frames post messages to your page, accepted only from the tiero origin and that frame:

Event	Payload	Component prop
`resize`	`{height}`	handled for you (board)
`saved`	`{listId, url}`	`onsaved`
`navigate`	`{url}`, only when it matches the list URL template	`onnavigate` (default: go to the URL)

The builder frame is max(640, window height - 24) pixels tall and scrolls inside.

API client

createTieroClient() gives typed, anonymous reads that work in the browser and on the server:

JavaScript

import { createTieroClient } from '@tiero/embed';

const client = createTieroClient({ timeoutMs: 3000 });
const catalog = await client.getCatalog('owner/slug');     // null on 404
const consensus = await client.getConsensus('owner/slug');
const list = await client.getList('YOUR_LIST_ID');
const page = await client.listLists({ catalog: 'owner/slug', sort: 'recent', limit: 24 });

Set baseUrl or pass your own fetch for another environment, and a final { signal } to cancel. Single-resource reads return null on 404. Other failures throw a TieroError with status, code and optional details; a timeout has status 0 and code timeout. The client reads public resources only.