widget.md

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.

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 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. The widget uses the same credits as the assistant.

Enable the widget

1. Navigate to your deployment's 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:

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:

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

AssistantAppearance

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.