​
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:

PropTypeDescription
connectionMintlifyWidgetConnectionPropsInformation needed to connect to our API. Required.
display?MintlifyWidgetDisplayPropsConfigurations for the widget appearance and interactions.
tracking?MintlifyWidgetTrackingFunctionsCallback functions for tracking analytics.

​
MintlifyWidgetConnectionProps

PropTypeDescription
apiKeystringWidget API key generated from Mintlify dashboard. Required.
url?stringUsed for internal testing only

​
MintlifyWidgetDisplayProps

PropTypeDescription
trigger?MintlifyWidgetDisplayTriggerPropsAppearance of the trigger.
colors?MintlifyWidgetDisplayColorsPropsColors used across the widget.
chat?MintlifyWidgetDisplayChatPropsConfigs specific to AI chat.
isDarkMode?booleanControlled dark mode appearance. Defaults to OS preference.

​
MintlifyWidgetDisplayTriggerProps

PropTypeDescription
type?'button'|'input'Type of the trigger to display. Defaults to button.
label?stringLabel 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?booleanOnly 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

PropTypeDescription
primary?stringPrimary color used in the widget. Defaults to #0D9373.
primaryLight?stringPrimary color in dark mode. Defaults to #55D799.

​
MintlifyWidgetDisplayChatProps

PropTypeDescription
openCitationInSameTab?booleanOpen 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

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

Was this page helpful?