live-layerdocs
View as markdown

NPM overview

Two packages, one origin:

  • @livelayer/react — the React-native widget. <AvatarWidget /> component, hooks (useLiveKitSession, useCollect), page-aware children (LiveLayerRegion).
  • @livelayer/sdk — framework-agnostic. Web component (<livelayer-widget>), LiveKitSession class, LiveLayerTracker, capability runner. The React package wraps this; you can also use it directly from Vue, Svelte, vanilla JS, or anywhere else.

This is the path with the most power and the most setup. Reach for it when:

  • Your app is React-based and the agent should access component state.
  • You need the agent to fill or submit forms in your app.
  • You need the agent to read text from your visible DOM.
  • You need a fully custom UI — your own avatar dock, your own controls.
  • You need an SSO-aware session minted by your own backend.
  • You want to build something live-layer doesn't ship out of the box (custom layouts, multi-agent dashboards, embedded coaching tools).

Install

bash
npm install @livelayer/react @livelayer/sdk
# or
pnpm add @livelayer/react @livelayer/sdk
# or
yarn add @livelayer/react @livelayer/sdk

The React package depends on the SDK, so installing both keeps you on a consistent version. They're released together.

Peer dependencies:

  • react >= 18.0.0
  • react-dom >= 18.0.0
  • livekit-client ^2.17.3 — installed automatically; do not duplicate

Hello world

tsx
import { AvatarWidget } from "@livelayer/react";
import "@livelayer/react/styles.css";

export default function App() {
  return <AvatarWidget agentId="agt_abc123" />;
}

That's it. The widget connects to app.livelayer.studio, fetches your published agent's config, and mounts a floating bubble.

What's next

The rest of these docs are the deep dive.

React API

  • Quickstart — minimal app + the most common props you'll touch first
  • AvatarWidget reference — every prop, every callback, every ref method
  • Page awareness — extractPageContext, LiveLayerRegion. Auto-discovered forms (no wrapper components). Lets the agent see what's on the page.
  • Data collection — onCollect, useCollect, structured TaskGroup-driven Q&A. Voice-first form filling with per-kind normalization.
  • Routing — showOn / hideOn, onNavigate, hooking into Next.js / React Router
  • Controlled session — own the LiveKit room yourself for cross-page persistence or shared rooms
  • Theming — branding, chromeless, compactControls, custom layouts
  • Hooks — useLiveKitSession, useAudioLevel, useMicrophoneState, et al. Build your own UI from primitives.

Framework-agnostic SDK

Types

  • TypeScript types — AgentState, ConnectionState, TranscriptEntry, AgentCommand, etc.

When NOT to use NPM

If you fit any of these, take an easier path first:

  • Marketing site, no React, just want a bubble → Script tag is one line of HTML.
  • Sharing the agent in email or QR codes → Hosted URL is zero code.
  • Embedding inside a CMS that won't run scripts → Iframe embed.

The NPM path is also the one you can graduate to later — switching from the script tag to the React component is straightforward, the agent IDs and dashboard configuration carry over.