Mintlify widget

The assistant answers questions on your Mintlify site. To embed the same capability on another site or web app, use the widget. With the widget, you can give your users access to AI chat trained on your content in your product dashboard, marketing site, support portal, or elsewhere.

Add the widget to any website or web application with a hosted script. The widget owns its trigger and renders inside a closed Shadow DOM, which prevents your application styles from affecting the widget.

The only required browser option is the public widget ID. Manage the enabled state, allowed origins, attachments, bot protection, and deflection contact form in your dashboard. Set embed-specific starter questions and a support email in the browser configuration.

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 you add 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,
});

defaultOpen defaults to false and only applies to the first initialization. Calling init() again with the same widget ID and API endpoint does not reopen a widget that a visitor closed. Use open() and close() to control it after initialization.

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: [
    "How do I get started with Mintlify?",
    "How do I customize my docs?",
    "How do I deploy my docs?",
  ],
});

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

To open the widget and immediately send a question, call ask():

await window.MintlifyAssistant.ask("How do I authenticate?", {
  source: "authentication-guide",
  open: true,
  focus: true,
});

Event metadata and requests include the source value, which lets you distinguish built-in interactions from your custom entry points.

Update a mounted widget

Use update() to change appearance, labels, support email, starter questions, or hooks without clearing the current conversation. Only the supplied fields change.

await window.MintlifyAssistant.update({
  appearance: {
    theme: "dark",
    accent: "#7c3aed",
  },
  labels: {
    title: "Docs copilot",
    trigger: "Ask docs",
  },
  supportEmail: "support@example.com",
  starterQuestions: [
    "How do I get started?",
    "How do I manage my account?",
  ],
});

Pass null to restore a field or group to its default, remove the support email, or restore an empty starter-question list:

await window.MintlifyAssistant.update({
  appearance: {
    accent: null,
  },
  supportEmail: null,
  starterQuestions: null,
  hooks: null,
});

Changing identity starts a new conversation. Changing the widget ID or API endpoint requires calling destroy() before a new init().

You can supply supportEmail and starterQuestions during initialization and change them later with update(). These values apply to the current embed and do not inherit from your Mintlify dashboard.

Scope retrieval by language or version

Use filter to restrict what the assistant retrieves when you organize your content by language or versions. Omit a field to search across every value for it.

await window.MintlifyAssistant.init({
  id: "YOUR_WIDGET_ID",
  filter: {
    language: "en",
    version: "v2",
  },
});

language must be a supported language code, such as en, es, fr, or zh-Hans. version matches the version name configured in your dashboard.

Change filters at runtime with update() when the visitor switches language or version in your application:

await window.MintlifyAssistant.update({
  filter: {
    language: "fr",
    version: null,
  },
});

Pass null on a field to clear that filter, or filter: null to clear both.

Configuration reference

AssistantConfig

Pass this object to init().

AssistantAppearance

Arbitrary CSS and neutral-palette overrides are not supported. The closed Shadow DOM protects both your application and the widget from cross-site style regressions.

AssistantFilter

AssistantLabels

AssistantHooks

hooks: {
  event(event) {
    console.log(event.type, event.actor, event.source);
  },
  error(error) {
    console.error(error.code, error.retryable, error.status);
  },
}

The event hook receives lifecycle and interaction metadata for init, open, close, ask, update, reset, navigate, and destroy. Events do not include question text, identity, session, or CAPTCHA tokens.

The error hook receives a stable code, a retryable boolean, and an optional HTTP status. Exceptions thrown by either hook do not interrupt the widget.

AssistantOpenOptions

Pass this optional object to open().

AssistantAskOptions

Pass this optional object after the question string in ask().

AssistantUpdate

Pass this object to update(). Every field is optional, and null restores its default.

Browser API

Conversation snapshots remain private to the widget. Each method resolves to void.

Content Security Policy

If your site uses a Content Security Policy, allow the origins required by your enabled widget features:

A strict script-src policy must still authorize both the loader and initialization script. A strict style-src policy must authorize the nonce you pass to init(), which the widget copies to its injected stylesheet. Passing nonce to init() propagates it only to resources the widget creates after initialization.