ExperienceWidget · Liforma Docs

Overview

<ExperienceWidget> is the homepage / support “floating widget” pattern: a collapsed corner preview that looks like ExperienceThumbnail, then expands to an in-page overlay when the user clicks. It is separate from the thumbnail (gallery cards stay cheap) and from a full-page <Experience> embed.

Pass only experience-id (and alt). On mount the widget calls GET /v1/experiences/{id}/preview to load gallery thumb plates — no API key and no origin allowlist. Session mint and allowlist checks happen only when the user expands.

Install

npm install @liforma/client

Surface	Import / tag
Vanilla / CMS	`<liforma-experience-widget>` via the CDN v2 script
Svelte	`@liforma/client/svelte`
React	`@liforma/client/react`
Next.js	`@liforma/client/next` (client component)

Hello world (HTML)

Host CSS owns corner placement and collapsed size. The widget fills its containing block. Preview images load without an allowlist; add your site origin in app.liforma.ai before users expand (session mint).

index.html

<!-- Liforma SDK: registers <liforma-experience-widget> and window.Liforma -->
<script src="https://cdn.liforma.ai/sdk/v2/client.js"><\/script>

<style>
  .liforma-widget-host {
    position: fixed;
    right: 16px;
    bottom: 16px;
    width: 224px;
    height: 224px;
    z-index: 9999;
  }
</style>

<div class="liforma-widget-host">
  <liforma-experience-widget
    experience-id="exp_01EXAMPLES_COFFEE_BARISTA"
    alt="Talk to our barista"
  ></liforma-experience-widget>
</div>

Svelte / React

Widget.svelte

<script>
  import { ExperienceWidget } from '@liforma/client/svelte';
</script>

<div class="liforma-widget-host">
  <ExperienceWidget
    experienceId="exp_01EXAMPLES_COFFEE_BARISTA"
    alt="Talk to our barista"
  />
</div>

SiteWidget.tsx

import { ExperienceWidget } from '@liforma/client/react';
// Next.js: import { ExperienceWidget } from '@liforma/client/next';

export function SiteWidget() {
  return (
    <div className="liforma-widget-host">
      <ExperienceWidget
        experienceId="exp_01EXAMPLES_COFFEE_BARISTA"
        alt="Talk to our barista"
      />
    </div>
  );
}

Loading model

When	What loads
Mount (collapsed)	Public preview API + CDN thumb plates (optional `gallery-thumb` skips the fetch)
Click expand (`prefetch="onExpand"`)	Session mint + player iframe; Tap to talk unlocks audio
`prefetch="idle"` / `eager`	Reserved for warm iframe (not shipped yet)

Mint options

Expand uses the same mint surface as <liforma-experience>: session-endpoint, language, mode, speech-input-mode, speech-only, fit, and start-button label.

vs ExperienceThumbnail

	Thumbnail	Widget
Role	Gallery / catalog preview	Site-wide conversation launcher
Thumb plates	Caller passes URLs	Fetched from preview API by default
Session / iframe	No (unless hosted launch)	Yes, after expand
Default open	Hosted player + returnUrl	In-page overlay

Example

Runnable demo: examples.liforma.ai — Experience widget (local http://localhost:4002 via ./start).