## Embed the AI assistant widget

Install and configure the Mintlify widget to embed an AI assistant trained on your content into any website, web app, or dashboard.

```javascript
export const AssistantWidgetPlayground = ({children, CodeBlockComponent}) => {
  const EXAMPLE_WIDGET_ID = "YOUR_WIDGET_ID";
  const EMBED_URL = "https://widget.mintlify.com/v1/embed.js";
  const SUPPORT_EMAIL = "hi@mintlify.com";
  const STARTER_QUESTIONS = ["How do I get started with Mintlify?", "How do I customize my docs?", "How do I deploy my docs?"];
  const VARIANT_OPTIONS = [{ value: "widget", label: "Widget" }, { value: "modal", label: "Modal" }, { value: "panel", label: "Panel" }];
  const RADIUS_OPTIONS = [{ value: 0, label: "None", detail: "0px" }, { value: 4, label: "Extra small", detail: "4px" }, { value: 8, label: "Small", detail: "8px" }, { value: 12, label: "Medium", detail: "12px" }, { value: 16, label: "Large", detail: "16px" }, { value: 20, label: "Extra large", detail: "20px" }, { value: 24, label: "2X large", detail: "24px" }];
  const SIDE_OPTIONS = [{ value: "bottom", label: "Bottom" }, { value: "top", label: "Top" }, { value: "left", label: "Left" }, { value: "right", label: "Right" }, { value: "inline-start", label: "Inline start" }, { value: "inline-end", label: "Inline end" }];
  const ALIGN_OPTIONS = [{ value: "start", label: "Start" }, { value: "center", label: "Center" }, { value: "end", label: "End" }];

// Various state and effect hooks

const installCode = `...`;  // installation code logic goes here
  return (
    <div data-assistant-playground-layout="">
      <section className="assistant-playground-frame not-prose" aria-label="Assistant widget playground">
        <div className="assistant-playground-code not-prose">
          <CodeBlockComponent language="jsx" filename="assistant-widget.jsx" wrap>
            {installCode}
          </CodeBlockComponent>
        </div>
        {children}
      </section>
    </div>
  );
};
```

The [assistant](/content/docs/assistant/index.html) answers questions on your Mintlify site. To embed the same capability on another site or web app, use the widget. The widget gives your users access to AI chat trained on your content, wherever they use your product. Embed it in your dashboard, marketing site, support portal, or elsewhere.

**Prerequisites**

* A [Pro or Enterprise plan](/content/pricing?ref=assistant/index.html). The widget uses the same credits as the assistant.

**Enable the widget**

1. Navigate to your deployment's [Widget](https://app.mintlify.com/settings/deployment/widget) page.
2. Enable the widget.
3. Add allowed origins where you embed the widget.
4. Copy the widget ID.

**Install and configure**

Use the playground to configure the presentation, visual options, and observer hooks for your widget. The installation code block updates as you change each option.

After adding the generated code to your site, reload the page. Confirm the trigger appears, then click it and send a test question to verify the connection.

## Open on initialization

Set `defaultOpen` to `true` to open the widget immediately after its first mount:

```javascript
await window.MintlifyAssistant.init({
  id: "YOUR_WIDGET_ID",
  defaultOpen: true,
});
```

## Use a custom trigger

Await `init()` before calling other methods. Keep the built-in trigger or open the configured presentation from any button in your application:

```javascript
await window.MintlifyAssistant.init({
  id: "YOUR_WIDGET_ID",
  supportEmail: "hi@mintlify.com",
  starterQuestions: STARTER_QUESTIONS,
});

document.querySelector("#help-button").addEventListener("click", () => {
  void window.MintlifyAssistant.open({
    source: "help-button",
    focus: true,
  });
});
```

## Configuration reference

### `AssistantConfig`

| Option             | Type                                                    | Description                                                           |
| ------------------ | ------------------------------------------------------- | --------------------------------------------------------------------- |
| `id`               | string                                                  | Public widget ID from the Mintlify dashboard.                         |
| `supportEmail`     | string                                                  | Sets the support address shown in the widget toolbar for this embed.  |
| `starterQuestions` | string\[]                                              | Sets up to three empty-state prompts for this embed.                  |

### `AssistantAppearance`

| Option                     | Values                                                         | Description                                                                                             |
| -------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `variant`                  | `widget`, `modal`, `panel`                                     | Controls whether the assistant opens as an anchored popover, centered dialog, or responsive side panel. |
| `theme`                    | `light`, `dark`, `system`                                      | Sets the widget color scheme. The default is `system`.                                                  |
| `accent`                   | CSS color                                                      | Sets the color of primary controls.                                                                     |
| `radius`                   | CSS border radius                                              | Sets the panel radius, such as `18px`.                                                                  |

### Hooks and Events

The `event` hook receives lifecycle and interaction metadata for `init`, `open`, `close`, and other operations. The widget maintains privacy for conversation snapshots, and errors can be logged with structured details using the hook.