Chat Widget

Getting started

First, generate an API key in the Mintlify dashboard.

Installation

Add the widget by adding these script tags into your site’s <head>...<head/> tag.

<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, use the React component from the @mintlify/widget-react package. Here is a basic example of how to use the component in your React application:

<MintlifyWidget
    connection={{
        apiKey: 'Your API key here',
    }}
/>

Usage

In the first script tag or the React component props, 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.
`url?`	`string`	Used for internal testing only

MintlifyWidgetDisplayProps

Prop	Type	Description
`trigger?`	MintlifyWidgetDisplayTriggerProps	Appearance of the trigger.
`colors?`	MintlifyWidgetDisplayColorsProps	Colors used across the widget.
`chat?`	MintlifyWidgetDisplayChatProps	Configs specific to AI 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.

Getting Started

Writing Content

API References

Configurations

Advanced

Getting started

Installation