Assistant Widget

Use @mintlify/assistant-widget to add your Mintlify assistant to any website or web application. The hosted package owns its trigger and renders inside a closed Shadow DOM, preventing your application styles from changing the widget. The only required browser option is the public Widget ID from your deployment’s Settings > Widget page. The enabled state, allowed origins, starter questions, attachments, and bot protection remain managed in the Mintlify dashboard.

Replace YOUR_WIDGET_ID in the generated code with the public Widget ID from your deployment.

Install and configure

Use the playground to configure the presentation, visual options, and observer hooks. The installation block updates as you change each option. Module scripts are deferred and run in document order. Keep the hosted loader before the initialization block when installing the widget with HTML.

Use a custom trigger

Await init() before calling other methods. You can keep the built-in trigger or open the configured presentation from any button in your application.

await window.MintlifyAssistant.init({
  id: "YOUR_WIDGET_ID",
});

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

The source value is included in event metadata and requests, which lets you distinguish built-in interactions from your custom entry points. Use update() to change appearance, labels, 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",
  },
});

Pass null to restore a field or group to its default:

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

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

Configuration reference

Appearance

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`.
`font`	CSS font family	Uses a font already loaded by your application. The default is bundled Inter.
`side`	`top`, `bottom`, `left`, `right`, `inline-start`, `inline-end`	Positions the built-in trigger on a screen edge.
`align`	`start`, `center`, `end`	Aligns the trigger along its selected edge.
`dismissOnInteractOutside`	boolean	Controls whether pointer or focus interactions outside close the assistant.
`logo`	URL or `{ light, dark }`	Replaces the default Mintlify mark.
`zIndex`	number	Changes the stacking order of the widget host.

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.

Hooks

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.

Browser API

Method	Description
`init(config)`	Loads and mounts the widget. This is the readiness promise for every other method.
`open(options)`	Opens the configured presentation.
`close()`	Closes the widget.
`ask(question, options)`	Opens the widget if requested and sends a question.
`update(config)`	Deep-patches mutable identity, appearance, label, and hook settings.
`reset()`	Starts a fresh conversation.
`destroy()`	Removes the widget and releases its browser resources.

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:

script-src: https://cdn.jsdelivr.net, https://challenges.cloudflare.com, and https://js.hcaptcha.com
connect-src: https://api.mintlify.com, https://challenges.cloudflare.com, and https://*.hcaptcha.com
frame-src: https://challenges.cloudflare.com and https://*.hcaptcha.com
style-src: https://cdn.jsdelivr.net and the nonce passed to init()
font-src: https://cdn.jsdelivr.net
img-src: any origins used by appearance.logo

A strict script-src policy must still authorize both the loader and initialization script. Passing nonce to init() propagates it only to resources the widget creates after initialization.

Get started

Organize

Customize

Create content

Document APIs

Deploy

Optimize

Install and configure

Use a custom trigger

Update a mounted widget

Configuration reference

Appearance

Hooks

Browser API

Content Security Policy

​Install and configure

​Use a custom trigger

​Update a mounted widget

​Configuration reference

​Appearance

​Hooks

​Browser API

​Content Security Policy

Install and configure

Use a custom trigger

Update a mounted widget

Configuration reference

Appearance

Hooks

Browser API

Content Security Policy