@keyframelabs/react

React bindings and UI components for Keyframe Labs. Built on top of @keyframelabs/elements.

Which package should I use?

• @keyframelabs/sdk (high control)
  • You implement the UI, state management, and agent/llm binding yourself
• @keyframelabs/elements (custom UI)
  • You implement the UI; we handle the state and agent/llm binding (framework-agnostic)
• @keyframelabs/react: (drop-in)
  • We handle the UI, state, and agent/llm binding

Install

pnpm add @keyframelabs/react

Usage

The PersonaEmbed component handles pretty much everything automatically. Just pass it your embed's publishable key (from the Keyframe platform dashboard).

import { PersonaEmbed } from '@keyframelabs/react';
import '@keyframelabs/react/styles.css';

function App() {
  return (
    <div style={{ width: '500px', height: '500px' }}>
      <PersonaEmbed
        publishableKey="kfl_pk_live_..."
        videoFit="contain"
        showControls={true}
        showStatus={true}
        onStateChange={(status) => console.log('Status:', status)}
        onAgentStateChange={(state) => console.log('Agent:', state)}
        onDisconnect={() => console.log('Session ended')}
        onError={(err) => console.error(err)}
      />
    </div>
  );
}

Customization

Override the default theme with CSS variables:

:root {
  --kfl-background: #ffffff;
  --kfl-foreground: #171717;
  --kfl-muted: rgba(0, 0, 0, 0.1);
  --kfl-muted-foreground: rgba(0, 0, 0, 0.5);
  --kfl-destructive: #dc2626;
  --kfl-destructive-foreground: #ffffff;
  --kfl-radius: 0.5rem;
  --kfl-font-family: 'Inter', sans-serif;
}

API

<PersonaEmbed />

| Prop | Type | Default | Description | | -------------------- | ------------------------------- | -------------------------------- | --------------------------------------------- | | publishableKey | string | Required | Your publishable embed key. | | apiBaseUrl | string | 'https://api.keyframelabs.com' | Base URL for the Keyframe API. | | videoFit | 'cover' \| 'contain' | 'cover' | Video scaling mode (object-fit). | | showControls | boolean | true | Whether to show mute and disconnect controls. | | showStatus | boolean | true | Whether to show the agent status indicator. | | className | string | — | Additional CSS classes applied to the root. | | onStateChange | (status: EmbedStatus) => void | — | Fired when connection status changes. | | onAgentStateChange | (state: AgentState) => void | — | Fired when agent state changes. | | onDisconnect | () => void | — | Fired when the session disconnects. | | onError | (err: Error) => void | — | Fired on errors. |

Exports

// Main component
import { PersonaEmbed } from '@keyframelabs/react';

// Types
import type { PersonaEmbedProps, EmbedStatus, AgentState, VideoFit } from '@keyframelabs/react';

// UI components (for custom implementations)
import { LoadingOverlay, ErrorOverlay, ControlsBar, StatusIndicator } from '@keyframelabs/react';

// Errors
import { KeyframeApiError } from '@keyframelabs/react';
import { KeyframeApiErrorPayload } from '@keyframelabs/react';

License

MIT