> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meridial.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# React setup

> Embed the React Voicebox widget in your app.

This guide shows how to embed Meridial Voicebox in your React app.

## 1) Install the package

```bash theme={null}
npm i @meridial/react
```

## 2) Embed Voicebox in your app

`<Voicebox />` is the single component you embed. It renders a trigger button and the user-facing support widget for live voice support and cobrowse escalation.

Add it where you want in-app support to be available:

```tsx theme={null}
"use client"

import { Voicebox } from "@meridial/react"

export function VoiceboxWidget({
  publishableKey,
  userId,
}: {
  publishableKey: string
  userId?: string
}) {
  return (
    <Voicebox
      publishableKey={publishableKey}
      identifier={userId}
      firstMessage="Hi, I'm your assistant. How can I help?"
      instructions="You are a helpful assistant that can answer questions and guide users through the product."
      metadata={{ orgId: "org_123", plan: "pro" }}
      sampleQuestions={[
        "How do I reset my password?",
        "Where can I update billing?",
      ]}
      onError={(err) => console.error("[Voicebox]", err)}
    />
  )
}
```

`publishableKey` comes from your [Meridial dashboard](https://app.meridial.dev). Use `identifier` to associate sessions with a specific user.

<Note>
  The `"use client"` directive is required in Next.js App Router. In other React
  setups (Vite, CRA, etc.) you can omit it.
</Note>

## Props

```ts theme={null}
interface VoiceboxProps {
  children?: React.ReactNode
  baseUrl?: string
  publishableKey?: string
  identifier?: string
  firstMessage?: string
  instructions?: string
  metadata?: Record<string, string>
  onError?: (error: string) => void
  tools?: VoiceboxTools
  sampleQuestions?: string[]
}
```

| Prop              | Description                                                                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `children`        | Custom content for the trigger button. Defaults to a "Help" label with an icon.                                                 |
| `publishableKey`  | Your Meridial publishable key.                                                                                                  |
| `identifier`      | Optional identifier for the current user. Used to associate sessions with a specific user in the dashboard.                     |
| `baseUrl`         | Meridial API base URL. Defaults to the hosted service.                                                                          |
| `firstMessage`    | The agent's opening message when a session starts.                                                                              |
| `instructions`    | System instructions that shape the agent's behavior.                                                                            |
| `metadata`        | Arbitrary key-value data attached to the session. Surfaces in the dashboard against the session record. Values must be strings. |
| `onError`         | Callback invoked when the widget encounters an error. Defaults to logging to the console.                                       |
| `tools`           | Tools the agent can call during a session. See [Agent tools](#agent-tools) below.                                               |
| `sampleQuestions` | Suggested prompts shown in the widget before a session starts.                                                                  |

## Custom trigger

Pass `children` to replace the default trigger button content:

```tsx theme={null}
<Voicebox publishableKey={publishableKey}>
  <img src="/support-avatar.png" alt="Get help" className="size-10 rounded-full" />
</Voicebox>
```

## Agent tools

The SDK exports `tool` and `useTool` so the agent can perform actions in your app (navigate, fill forms, read state, and so on).

Define a tool with a Zod input schema and an `execute` handler:

```tsx theme={null}
import { Voicebox, tool } from "@meridial/react"
import { z } from "zod"

<Voicebox
  publishableKey={publishableKey}
  tools={{
    navigateToPath: tool({
      description: "Navigate to a path in the app",
      inputSchema: z.object({ path: z.string() }),
      execute: async ({ path }) => {
        router.push(path)
        return `Navigating to ${path}`
      },
    }),
  }}
/>
```

### Registering tools from child components

When a tool needs access to local component state (for example, a form on the current page), use `useTool` instead of passing tools through `Voicebox` props:

```tsx theme={null}
import { tool, useTool } from "@meridial/react"
import { z } from "zod"

const schema = z.object({
  firstName: z.string(),
  lastName: z.string(),
})

function SettingsPage() {
  const form = useForm({ /* ... */ })

  useTool({
    tools: {
      enterPersonalInformation: tool({
        description: "Fill in the user's personal information",
        inputSchema: schema,
        execute: async (input) => {
          form.reset(input)
          return "Personal information updated."
        },
      }),
    },
    onToolCall: (event) => {
      console.log("Tool called:", event.toolId, event.response)
    },
  })

  return <form>{/* ... */}</form>
}
```

Tools registered via `useTool` are merged with any tools passed to `<Voicebox />`. On key conflicts, hook-registered tools take precedence.

## Styling

The component uses Tailwind CSS and is designed to work with existing Tailwind / shadcn setups. Two options:

### Option 1: scan the package with your Tailwind build

In your global stylesheet:

```css theme={null}
@source "../node_modules/@meridial/react/dist/**/*.{js,mjs}";
```

Adjust the relative path to match your stylesheet's location.

### Option 2: import the prebuilt CSS

If you don't want Tailwind to scan the package:

```css theme={null}
@import "@meridial/react/dist/styles.css";
```