mintlify__docs/customize/custom-scripts.mdx

---
title: "Custom scripts"
description: "Add custom JavaScript and CSS scripts to your documentation site for analytics, widgets, styling overrides, and third-party integrations."
keywords: ["CSS", "JavaScript", "Tailwind CSS", "style customization"]
---

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.

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

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

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

```css
#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.

<Tip>
  Use inspect element to find references to elements you're looking to customize.
</Tip>

<AccordionGroup>
  <Accordion title="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`
  </Accordion>
  <Accordion title="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`):

    - Active item in a nav dropdown: `nav-dropdown-item[data-active]`
    - Active tab in the mobile nav: `mobile-nav-tabs-item[data-active]`
    - Active sidebar group: `sidebar-group[data-active]`
    - Active sidebar link: `#sidebar-content li[data-active]`
    - Active top nav tab: `.nav-tabs-item[data-active]` — only applies to simple tabs; tabs with dropdown menus do not receive `data-active`. Note the leading `.`: this targets a class on a standard `<a>` element, unlike most other components which use custom element names.
    - Active table of contents item: `toc-item[data-active]`
    - Deepest active table of contents item: `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.

    Component name (`data-component-name`):

    Use `data-component-name` to target specific UI components with a stable selector that persists if internal class names change.

    - Mermaid diagram wrapper: `[data-component-name="mermaid-container"]` — includes the zoom controls overlay
    - Mermaid zoom and pan controls: `[data-component-name="mermaid-controls-wrapper"]`
    - Primary header button: `[data-component-name="primary-header-button"]` — Sequoia theme only
    - Theme toggle: `[data-component-name="theme-toggle"]`

    Badge attributes:

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

  </Accordion>
</AccordionGroup>

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

## 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](https://marketingplatform.google.com/about/analytics) across the entire documentation.

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

gtag('config', 'TAG_ID');
```

<Warning>
  Please use with caution to not introduce security vulnerabilities.
</Warning>