Custom scripts

Add custom JavaScript and CSS for analytics, widgets, styling, third-party integrations, and API playground server variables on your documentation site.

Use CSS to style HTML elements or add custom CSS and JavaScript to fully customize the look and feel of your documentation.

Style with Tailwind CSS

Use Tailwind CSS v3 to style HTML elements and components. You can control layout, spacing, colors, and other visual properties. Some common classes are:

w-full - Full width
aspect-video - 16:9 aspect ratio
rounded-xl - Large rounded corners
block, hidden - Display control
dark:hidden, dark:block - Dark mode visibility

Style components with `className`

Components accept a className prop. Mintlify merges your classes with the component's own styles, so you can restyle a single instance without wrapping it in extra markup or writing a CSS override.

className

<Note className="mt-0">This callout has no top margin.</Note>

<Card title="Quickstart" href="/quickstart" className="border-2 border-blue-500">
  Deploy your first documentation site.
</Card>

Three components do not accept className: Banner, MDX, and Visibility.

Arbitrary values and variants

Use arbitrary values when no utility class covers the value that you need.

Arbitrary

<img src="/images/diagram.png" alt="System architecture diagram" className="w-[450px]" />

<Frame className="lg:w-[calc(100%-2rem)] bg-[#0f172a]">
  <img src="/images/hero.png" alt="Product hero image" />
</Frame>

Variants work as they do in any Tailwind project, including responsive prefixes (sm:, md:, lg:), state variants (hover:, focus:), dark:, data attribute variants (data-[state=open]:), opacity modifiers (bg-black/50), and the ! important modifier.

Mintlify generates CSS for the Tailwind classes that it finds in your page source, so write class names out in full.

Write

{/* Generates CSS: the full class name appears in the page source. */}
<div className="bg-blue-500" />

{/* Generates no CSS: the class name is assembled at runtime. */}
<div className={`bg-${color}-500`} />

Add custom CSS

Mintlify includes any .css file inside your content directory on every page of your site. The content directory is the folder in your repository that contains your docs.json file and MDX pages. You do not need to import or reference the file from docs.json or your MDX files.

To add custom styles, create a .css file in your content directory. Any class names, ID selectors, or element selectors you define become available across all of your MDX files.

For example, define a class in style.css:

Example

.my-callout {
  border-radius: 1rem;
  background: #f0f9ff;
  padding: 1rem;
}

You can combine custom class names with Tailwind CSS classes on the same element.

The references and styling of common elements are subject to change. Use custom styling with caution since breaking changes may occur in future updates.

For example, you can add the following style.css file to customize the styling of the navbar and footer.

CSS

#navbar {
  background: #fffff2;
  padding: 1rem;
}

footer {
  margin-top: 2rem;
}

Mintlify exposes two types of CSS targeting hooks:

ID selectors: unique page-level elements targeted with #value { } in CSS
Element selectors: component and layout elements targeted with value { } in CSS (no # or . prefix)

ID selectors

Each ID appears once per page. Use these as #value in CSS. For example, #navbar { background: red; }.

Page layout

#body-content: Outermost wrapper for the page body.
#content-area: Primary content area, excluding the sidebar and table of contents.
#content: Inner content element within the content area.
#header: Page-level header element.
#banner: Announcement banner displayed above the navbar.
#footer: Page footer. Also targetable as an element selector: footer.
#page-title: The <h1> heading at the top of each page.
#pagination: Bottom pagination bar with previous and next page links.
#panel: Floating panel overlay. Also targetable as an element selector: panel.
#background-color: Page background color element.

Table of contents

#table-of-contents: Table of contents panel on the right side of the page.
#table-of-contents-layout: Layout wrapper for the table of contents.
#table-of-contents-content: Scrollable content within the table of contents.

#search-bar-entry: Search bar trigger in the topbar.
#search-bar-entry-mobile: Search bar trigger on mobile.
#search-input: Text input field within the search modal.

AI assistant

#assistant-entry: AI assistant button in the topbar.
#assistant-entry-mobile: AI assistant button on mobile.
#chat-assistant-sheet: AI assistant chat panel.
#chat-assistant-textarea: Text input within the AI assistant panel.

API reference

#request-example: Request example panel in the API playground.
#response-example: Response example panel in the API playground.
#api-playground-input: Input section of the API playground.
#endpoints-menu-trigger: Button that opens the endpoint selector dropdown.

Code blocks

#ask-assistant-code-block-button: "Ask Assistant" button that appears on code blocks.
#code-snippet-feedback-button: Feedback button on code snippets.
#code-snippet-feedback-textarea: Text area within the code snippet feedback form.

Feedback

#feedback-thumbs-up: Thumbs-up feedback button at the bottom of a page.
#feedback-thumbs-down: Thumbs-down feedback button at the bottom of a page.
#feedback-form: Feedback form shown after a thumbs-down response.
#feedback-form-input: Text input within the feedback form.
#feedback-form-cancel: Cancel button within the feedback form.
#feedback-form-submit: Submit button within the feedback form.

Localization

#localization-select-trigger: Button that opens the language selector.
#localization-select-content: Dropdown content of the language selector.
#localization-select-item: Individual language option within the selector.

Changelog

#changelog-filters: Filter controls on a changelog page.
#changelog-filters-content: Content area within the changelog filter panel.

Multi-view

#multi-view-dropdown: Dropdown for switching between documentation views.

Text selection

#text-selection-tooltip: Tooltip that appears when you select text on a page.
#text-selection-tooltip-button: Action button within the text selection tooltip.

Element selectors

Multiple instances of these elements can appear on a page. Use these as value in CSS. For example, accordion { border: 1px solid red; }.

Content components

accordion: Collapsible accordion item.
accordion-group: Wrapper grouping multiple accordions.
callout: Callout block (Note, Warning, Tip, etc.).
card: Individual card element.
card-group: Wrapper grouping multiple cards. Deprecated in favor of columns, but preserved for backward compatibility.
columns: Multi-column layout wrapper.
code-block: Code block element.
code-block-icon: Icon displayed in a code block header.
code-block-copy-button: Copy button shown on a code block. Hide it with .code-block-copy-button { display: none; }.
code-block-fade-overlay: Fade overlay shown at the bottom of a collapsed code block.
code-group: Tabbed group of code blocks.
expandable: Expandable section element.
frame: Frame wrapper for images or embedded content.
icon: Inline icon element.
mermaid: Mermaid diagram wrapper.
step: Individual step within a steps sequence.
steps: Numbered steps container.
tab-icon: Icon displayed within a tab.
tabs: Tabbed content container.
tile: Tile component element.
tooltip: Tooltip element.
update: Changelog update entry.

Page layout

mdx-content: Rendered MDX content area.
panel: Floating panel component. Also targetable as an ID selector: #panel.
eyebrow: Small label displayed above a page title.
link: Anchor link element.
breadcrumb-list: Breadcrumb navigation list.
breadcrumb-item: Individual breadcrumb item.

Topbar navigation

nav-logo: Logo image in the navigation bar. To override its default size utilities, target img.nav-logo and use !important.
CSS
```
img.nav-logo {
  height: 3.75rem !important;
  width: auto !important;
}
```
navbar-link: Link element within the navigation bar.
nav-anchors: Container for anchor links in the topbar.
nav-anchor: Individual anchor link in the topbar.
nav-tabs: Tab bar in the top navigation.
nav-tabs-item: Individual tab item in the top navigation tab bar.
mobile-nav-tabs-item: Tab item in the mobile navigation tab bar.
topbar-right-container: Right section of the topbar.
nav-tag-pill: Tag pill shown in the navigation.
nav-tag-pill-text: Text within a navigation tag pill.

Products selector

nav-dropdown-products-selector-trigger: Button that opens the products selector dropdown.
nav-dropdown-products-selector-content: Content container for the products selector.
nav-dropdown-products-selector-item: Individual product in the selector.
nav-dropdown-products-selector-item-title: Title of a product selector item.
nav-dropdown-products-selector-item-description: Description of a product selector item.
nav-dropdown-products-selector-item-icon: Icon of a product selector item.

Table of contents

toc: Table of contents container.
toc-item: Individual heading entry in the table of contents.

Footer

footer: Standard page footer. Also targetable as an ID selector: #footer.
advanced-footer: Extended footer with additional columns or content.

Pagination

pagination-prev: Previous page link in the pagination bar.
pagination-next: Next page link in the pagination bar.
pagination-title: Page title shown in the pagination bar.

API reference

api-section: Full section for a single API endpoint.
api-section-heading: Heading area for an API endpoint section.
api-section-heading-title: Title within an API endpoint section heading.
api-section-heading-subtitle: Subtitle within an API endpoint section heading.
field: Parameter or property field in the API reference.
option-dropdown: Dropdown for selecting between API options.
tryit-button: "Try it" button that opens the API playground.
method-pill: HTTP method badge (GET, POST, etc.) on an endpoint.
method-nav-pill: HTTP method badge shown in the sidebar navigation.
prompt: Prompt component in the API reference.

AI assistant

chat-assistant-sheet: AI assistant panel container.
chat-assistant-sheet-header: Header of the AI assistant panel.
chat-assistant-sheet-content: Content area of the AI assistant panel.
chat-assistant-input: Text input within the AI assistant panel.
chat-assistant-floating-input: Floating input variant of the AI assistant.
chat-assistant-send-button: Send button in the AI assistant panel.
chat-assistant-disclaimer-text: Disclaimer text displayed in the AI assistant panel.
chat-assistant-payload-item: Individual message or result item in the assistant panel.
starter-question-text: Suggested starter question shown in an empty assistant panel.

Feedback

feedback-toolbar: Toolbar containing page feedback controls.
contextual-feedback-container: Container for contextual inline feedback.
contextual-feedback-form: Inline contextual feedback form.
contextual-feedback-form-title: Title of the contextual feedback form.
contextual-feedback-input: Text input within the contextual feedback form.
contextual-feedback-button: Action button within the contextual feedback form.
contextual-feedback-form-submit-button: Submit button for the contextual feedback form.

Code snippet feedback

code-snippet-feedback-popover-content: Popover content for code snippet feedback.
code-snippet-feedback-form: Feedback form for a code snippet.
code-snippet-feedback-textarea: Text area within the code snippet feedback form.
code-snippet-feedback-form-title: Title of the code snippet feedback form.
code-snippet-feedback-form-description: Description text in the code snippet feedback form.
code-snippet-feedback-form-submit-button: Submit button for the code snippet feedback form.

Authentication

login-link: Link that initiates the login flow.
logout-link: Link that initiates the logout flow.

Multi-view

multi-view-item: Individual view option in a multi-view switcher.
multi-view-dropdown: Dropdown for selecting between multiple views.
multi-view-dropdown-trigger: Button that opens the multi-view dropdown.
multi-view-dropdown-content: Content area of the multi-view dropdown.
multi-view-dropdown-item: Individual item within the multi-view dropdown.

Custom JavaScript

Custom JavaScript lets you add custom executable code globally. It is the equivalent of adding a <script> tag with JavaScript code into every page.

Mintlify includes any .js file inside your content directory on every page of your site. Custom JavaScript files run after the page becomes interactive. You cannot scope them to specific pages. When you include multiple .js files, they run without a guaranteed order.

To load a third-party script, inject a <script> element from your custom JavaScript file instead of adding raw <script src="..."> tags in MDX:

Example

const script = document.createElement('script');
script.src = 'https://example.com/widget.js';
script.async = true;
document.head.appendChild(script);

For example, you can add the following ga.js file to enable Google Analytics across your entire site.

JavaScript

window.dataLayer = window.dataLayer || [];
function gtag() {
  dataLayer.push(arguments);
}
gtag('js', new Date());

gtag('config', 'TAG_ID');

Set API playground server variables

Use window.mintlify.api.playground.setServerVariables to prefill OpenAPI server variables from custom JavaScript. Use it when values become available after page load. For example, after authentication or a tenant change.

Pass an object of string values. Each call replaces the previous runtime values, which take precedence over OpenAPI defaults and saved values.

Set

window.mintlify.api.playground.setServerVariables({
  tenantDomain: 'example.us.auth0.com',
});

To remove the runtime values, call:

Clear

window.mintlify.api.playground.clearServerVariables();

Calls made before the client initializes queue. Values apply to open and future playgrounds for the current page session and reset after a full-page refresh.

Access personalized user data

If your site uses authentication or personalization, custom scripts can read the identified visitor from window.mintlify.user. This is the same object exposed to MDX pages as the user variable, so it reflects the content field of your user data.

Because custom scripts run before user info resolves, listen for the mintlify:user event to identify when the user object is available. The event fires when user info resolves and again on any change. Its detail is the user object, or null when the visitor is signed out or unidentified.

Read

window.addEventListener('mintlify:user', (event) => {
  const user = event.detail;
  if (!user) return; // Signed out or unidentified.

  renderAppLauncher(user);
});

If the user has already resolved by the time your script runs, read window.mintlify.user directly.

Read

const user = window.mintlify?.user;
if (user) {
  renderAppLauncher(user);
}

window.mintlify.user is undefined until user info resolves and when the visitor is signed out or unidentified. Use optional chaining when reading nested fields.

Style with Tailwind CSS

Style components with className

Arbitrary values and variants

Add custom CSS

ID selectors

Element selectors

Custom JavaScript

Set API playground server variables

Access personalized user data

Related topics

Style components with `className`