<script>
    window.mintlifyWidgetSettings = {
        connection: {
            apiKey: 'Your API key here'
        },
    };
</script>
<script>
    (function () {
        if (!document.getElementById('mintlify-widget')) {
            var script = document.createElement('script');
            script.id = 'mintlify-widget';
            script.src = 'https://unpkg.com/@mintlify/widget@^0';
            script.onload = () => MintlifyWidget.init();
            document.head.appendChild(script);
        }
    })();
</script>

To use the widget in React and Next.js apps, please check out the React component from the @mintlify/widget-react package on NPM.

Usage

In the first script tag, you can customize the appearance and other settings of the widget. mintlifyWidgetSettings accepts the following props:

Prop	Type	Description
`connection`	MintlifyWidgetConnectionProps	Information needed to connect to our API. Required.
`display?`	MintlifyWidgetDisplayProps	Configurations for the widget appearance and interactions.
`tracking?`	MintlifyWidgetTrackingFunctions	Callback functions for tracking analytics.

MintlifyWidgetConnectionProps

Prop	Type	Description
`apiKey`	`string`	Widget API key generated from Mintlify dashboard. Required.

MintlifyWidgetDisplayProps

Prop	Type	Description
`trigger?`	MintlifyWidgetDisplayTriggerProps	Appearance of the trigger.
`colors?`	MintlifyWidgetDisplayColorsProps	Colors used across the widget.
`chat?`	MintlifyWidgetDisplayChatProps	Configs specific to Mintlify chat.
`isDarkMode?`	`boolean`	Controlled dark mode appearance. Defaults to OS preference.

MintlifyWidgetDisplayTriggerProps

Prop	Type	Description
`type?`	`'button'`\|`'input'`	Type of the trigger to display. Defaults to `button`.
`label?`	`string`	Label displayed in the trigger. Defaults to `Get help` for the button trigger and `Ask anything...` for the input trigger.
`buttonIcon?`	`'chat'`\|`'sparkles'`\|`'mintlify'`	Icon used in the trigger. Only available for the `button` trigger. Defaults to `chat`.
`iconOnly?`	`boolean`	Only show icon in the trigger or not. Defaults to `false`.

Here is an overview of what the trigger looks like with different configurations.

`type='input'`

`type='button'`	`'chat'`	`'sparkles'`	`'mintlify'`
`iconOnly=false`
`iconOnly=true`

MintlifyWidgetDisplayColorsProps

Prop	Type	Description
`primary?`	`string`	Primary color used in the widget. Defaults to `#0D9373`.
`primaryLight?`	`string`	Primary color in dark mode. Defaults to `#55D799`.

MintlifyWidgetDisplayChatProps

Prop	Type	Description
`openCitationInSameTab?`	`boolean`	Open the citation url in the same tab or not. Defaults to `false`.
`exampleQueries?`	`string[]`	Example queries to prompt the user to ask. Defaults to `[]`.

MintlifyWidgetTrackingFunctions

Prop	Type	Description
`trackChatEnter`	`()=> void`	Triggered when the user opens the chat widget.
`trackCitationClick`	`(title: string, url: string)=> void`	Triggered when the user clicks on a citation.
`trackChatThumbsUp`	`(query: string, response: string)=> void`	Triggered when the user thumbs up on a response.
`trackChatThumbsDown`	`(query: string, response: string)=> void`	Triggered when the user thumbs down on a response.
`trackChatFollowup`	`(query: string)=> void`	Triggered when the user asks a question.
`trackChatClose`	`(queriesCount: number)=> void`	Triggered when the user exits the chat widget.

Questions and Support

If you have any questions or need support on using the widget, please reach out to us via support@mintlify.com.

If you're new to Mintlify, sign up today at mintlify.com.

FAQs

Package last updated on 19 Dec 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@mintlify/widget

Mintlify Widget

Getting started

Installation