npm package: @keyframelabs/react
Description: React bindings and UI components for Keyframe Labs.
Latest version: 0.1.0

# @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 (
    <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:

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

### `<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

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