Custom scripts

Add custom JavaScript and CSS to fully customize the look and feel of your documentation.

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. 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

Tailwind CSS arbitrary values are not supported. For custom values, use the style prop instead.

<img style={{ width: '350px', margin: '12px auto' }} src="/path/image.jpg" />

Using the style prop can cause a layout shift on page load, especially on custom mode pages. Use Tailwind CSS classes or custom CSS files instead to avoid shifts or flickering.

Add custom CSS

Add CSS files to your repository to apply their defined class names and make them available in all of your MDX files.

Adding style.css

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

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

footer {
  margin-top: 2rem;
}

Using identifiers and selectors

Mintlify has a set of common identifiers and selectors to help you tag important elements of the UI.

Use inspect element to find references to elements you’re looking to customize.

Identifiers

• APIPlaygroundInput: api-playground-input
• AssistantEntry: assistant-entry
• AssistantEntryMobile: assistant-entry-mobile
• Banner: banner
• BodyContent: body-content
• ChangelogFilters: changelog-filters
• ChangelogFiltersContent: changelog-filters-content
• ChatAssistantSheet: chat-assistant-sheet
• ChatAssistantTextArea: chat-assistant-textarea
• ContentArea: content-area
• ContentContainer: content-container
• ContentSideLayout: content-side-layout
• FeedbackForm: feedback-form
• FeedbackFormCancel: feedback-form-cancel
• FeedbackFormInput: feedback-form-input
• FeedbackFormSubmit: feedback-form-submit
• FeedbackThumbsDown: feedback-thumbs-down
• FeedbackThumbsUp: feedback-thumbs-up
• Footer: footer
• Header: header
• NavBarTransition: navbar-transition
• NavigationItems: navigation-items
• Navbar: navbar
• PageContextMenu: page-context-menu
• PageContextMenuButton: page-context-menu-button
• PageTitle: page-title
• Pagination: pagination
• Panel: panel
• RequestExample: request-example
• ResponseExample: response-example
• SearchBarEntry: search-bar-entry
• SearchBarEntryMobile: search-bar-entry-mobile
• SearchInput: search-input
• Sidebar: sidebar
• SidebarContent: sidebar-content
• TableOfContents: table-of-contents
• TableOfContentsContent: table-of-contents-content
• TableOfContentsLayout: table-of-contents-layout
• TopbarCtaButton: topbar-cta-button

Selectors

• Accordion: accordion
• AccordionGroup: accordion-group
• AlmondLayout: almond-layout
• AlmondNavBottomSection: almond-nav-bottom-section
• AlmondNavBottomSectionDivider: almond-nav-bottom-section-divider
• Anchor: nav-anchor
• Anchors: nav-anchors
• APISection: api-section
• APISectionHeading: api-section-heading
• APISectionHeadingSubtitle: api-section-heading-subtitle
• APISectionHeadingTitle: api-section-heading-title
• Callout: callout
• Card: card
• CardGroup: card-group
• ChatAssistantSheet: chat-assistant-sheet
• ChatAssistantSheetHeader: chat-assistant-sheet-header
• ChatAssistantSheetContent: chat-assistant-sheet-content
• ChatAssistantInput: chat-assistant-input
• ChatAssistantSendButton: chat-assistant-send-button
• CodeBlock: code-block
• CodeGroup: code-group
• Content: mdx-content
• DropdownTrigger: nav-dropdown-trigger
• DropdownContent: nav-dropdown-content
• DropdownItem: nav-dropdown-item
• DropdownItemTextContainer: nav-dropdown-item-text-container
• DropdownItemTitle: nav-dropdown-item-title
• DropdownItemDescription: nav-dropdown-item-description
• DropdownItemIcon: nav-dropdown-item-icon
• Expandable: expandable
• Eyebrow: eyebrow
• FeedbackToolbar: feedback-toolbar
• Field: field
• Frame: frame
• Icon: icon
• Link: link
• LoginLink: login-link
• Logo: nav-logo
• Mermaid: mermaid
• MethodNavPill: method-nav-pill
• MethodPill: method-pill
• NavBarLink: navbar-link
• NavTagPill: nav-tag-pill
• NavTagPillText: nav-tag-pill-text
• OptionDropdown: option-dropdown
• PaginationNext: pagination-next
• PaginationPrev: pagination-prev
• PaginationTitle: pagination-title
• Panel: panel
• SidebarGroup: sidebar-group
• SidebarGroupIcon: sidebar-group-icon
• SidebarGroupHeader: sidebar-group-header
• SidebarNavGroupDivider: sidebar-nav-group-divider
• SidebarTitle: sidebar-title
• Step: step
• Steps: steps
• Tab: tab
• Tabs: tabs
• TabsBar: nav-tabs
• TabsBarItem: nav-tabs-item
• TableOfContents: toc
• TableOfContentsItem: toc-item
• Tooltip: tooltip
• TopbarRightContainer: topbar-right-container
• TryitButton: tryit-button
• Update: update

Data attributes

Some elements expose data attributes you can use as CSS selectors.

Active state (data-active):

• DropdownItem: nav-dropdown-item[data-active]
• MobileNavTabsBarItem: mobile-nav-tabs-item[data-active]
• SidebarGroup: sidebar-group[data-active]
• SidebarNavItem: #sidebar-content li[data-active]
• TableOfContentsItem: toc-item[data-active]
• TableOfContentsItem (deepest): toc-item[data-active-deepest] Only present on the exact heading currently in view, unlike data-active which is also set on its parent headings

Badge attributes:

• Badge: [data-badge]
• Badge by color: [data-badge][data-color="blue"]
• Badge by size: [data-badge][data-size="sm"]

References and the styling of common elements are subject to change as the platform evolves. Please use custom styling with caution.

Custom JavaScript

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

Adding custom JavaScript

Mintlify includes any .js file inside your content directory on every page of your documentation site. For example, you can add the following ga.js file to enable Google Analytics across the entire documentation.

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

gtag('config', 'TAG_ID');

Please use with caution to not introduce security vulnerabilities.

External scripts

Load third-party scripts from external URLs on every page of your documentation site. This is useful for adding analytics, chat widgets, consent managers, or other services that provide a hosted script.

You can manage external scripts from the dashboard under Settings > Add-ons > Custom scripts. For each script, provide an HTTPS URL and choose a loading strategy:

Strategy	Description
beforeInteractive	Loads before the page becomes interactive. Use for scripts that must run before any user interaction, such as cookie consent or critical analytics.
afterInteractive	Loads after the page becomes interactive. This is the default behavior when no strategy is specified.
lazyOnload	Loads during idle time after page load. Use for low-priority scripts like chat widgets or non-essential tracking.

You can add up to 20 custom scripts. Each URL must use HTTPS and must not point to disallowed file types such as .svg, .exe, or .zip.