@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

``bash
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).

`tsx

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

function App() {
return (



);
}
`

Customization

Override the default theme with CSS variables:

`css
: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

$3

| 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

`tsx
// 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