Skip to main content
@mintlify/components is built with Tailwind CSS and requires either Tailwind v3 or v4 to function properly. This guide walks you through the setup process for both versions.

​
Requirements

Before you begin, ensure you have:
  • Node.js >= 20.0.0
  • React ^18.0.0 or ^19.0.0
  • Tailwind CSS v3 or v4

​
Installation

1

Install the package

First, install @mintlify/components using your preferred package manager:
npm install @mintlify/components
2

Choose your Tailwind version

Follow the setup instructions below based on your Tailwind CSS version.

​
Tailwind CSS v4 Setup

Tailwind v4 uses a new CSS-first configuration approach with @theme directives.
Import the component styles at the top of your main CSS file, before importing Tailwind:
styles.css
@import "@mintlify/components/styles.css";
@import "tailwindcss";

@theme {
  --color-primary: #166534;
  --color-primary-light: #f0f9f4;
  --color-primary-dark: #2d5a3d;
}
The order is critical! Importing @mintlify/components/styles.css before tailwindcss ensures your custom theme values take precedence over component defaults.

​
Available Theme Variables

Customize the component appearance using these CSS variables:
VariableDescriptionDefault
--color-primaryPrimary brand colorrgb(22, 101, 52)
--color-primary-lightLight variant of primary colorrgb(240, 249, 244)
--color-primary-darkDark variant of primary colorrgb(45, 90, 61)
--color-tooltip-foregroundTooltip text colorrgb(255, 255, 255)
--color-background-darkDark mode backgroundrgb(14, 14, 15)

​
Complete Example

styles.css
@import "@mintlify/components/styles.css";
@import "tailwindcss";

@plugin "@tailwindcss/typography";

@theme {
  /* Brand colors */
  --color-primary: #3b82f6;
  --color-primary-light: #dbeafe;
  --color-primary-dark: #1e40af;
  
  /* UI colors */
  --color-tooltip-foreground: #ffffff;
  --color-background-dark: #0f172a;
}

@layer base {
  html {
    font-feature-settings: "cv02", "cv03", "cv04", "cv11";
  }
}

​
Tailwind CSS v3 Setup

For Tailwind v3, import the component styles at the top of your CSS file:
styles.css
@import "@mintlify/components/styles.css";
@tailwind base;
@tailwind components;
@tailwind utilities;

​
Configuration File

Create or update your tailwind.config.js to customize the theme:
tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
    './node_modules/@mintlify/components/**/*.{js,jsx,ts,tsx}'
  ],
  theme: {
    extend: {
      colors: {
        primary: {
          DEFAULT: '#166534',
          light: '#f0f9f4',
          dark: '#2d5a3d',
        },
        background: {
          dark: '#0e0e0f',
        },
      },
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
  ],
}
Make sure to include the component files in your content array so Tailwind can detect which classes are being used.

​
Using the cn Utility

The library exports a cn utility function for merging Tailwind classes. This utility combines clsx and tailwind-merge to intelligently merge class names and resolve conflicts: 
import { cn } from '@mintlify/components';

function MyComponent({ className, isActive }) {
  return (
    <div className={cn(
      'base-class rounded-lg p-4',
      'text-blue-500 hover:text-blue-700',
      isActive && 'bg-blue-50 dark:bg-blue-900',
      className
    )}>
      Content
    </div>
  );
}
The cn utility is especially useful when:
  • Combining conditional classes
  • Merging user-provided className props
  • Resolving conflicting Tailwind classes (e.g., text-blue-500 and text-red-500 won’t both apply)

​
Working with Component Styles

​
Understanding Dark Mode Classes

Components use Tailwind’s dark: variant for dark mode styling. For example, the Callout component uses classes like: 
// From source/packages/components/src/components/callout/callout.tsx:41-42
border border-stone-200 bg-stone-50 
dark:border-stone-700 dark:bg-white/10

​
Custom Styling Components

You can override component styles using the className prop: 
import { Callout } from '@mintlify/components';

<Callout 
  variant="info"
  className="border-2 border-blue-500 shadow-lg"
>
  Custom styled callout
</Callout>

​
Advanced Tailwind Features

​
Using Arbitrary Values

The library supports Tailwind’s arbitrary value syntax: 
import { Card } from '@mintlify/components';

<Card 
  title="Custom Card"
  className="bg-[#f0f9f4] hover:bg-[#dcf4e3]"
/>

​
Responsive Design

All components work seamlessly with Tailwind’s responsive modifiers: 
import { Badge } from '@mintlify/components';

<Badge 
  className="text-xs md:text-sm lg:text-base"
  size="sm"
>
  Responsive Badge
</Badge>

​
Troubleshooting

Ensure you’ve imported @mintlify/components/styles.css at the top of your CSS file, before Tailwind imports.For Tailwind v3:
@import "@mintlify/components/styles.css";
@tailwind base;
For Tailwind v4:
@import "@mintlify/components/styles.css";
@import "tailwindcss";
In Tailwind v4, verify that your @theme block comes after the component imports. In v3, check that you’re extending the theme correctly in tailwind.config.js.Also ensure you’re using the correct CSS variable names like --color-primary and --color-primary-dark.
Make sure the component files are included in your Tailwind content configuration:
tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
    './node_modules/@mintlify/components/**/*.{js,jsx,ts,tsx}'
  ],
}
If you’re seeing unused styles or missing styles in production, verify your PurgeCSS/content configuration includes both your source files and the component library.

​
Next Steps

Dark Mode

Set up dark mode and customize theme colors

TypeScript

Learn about TypeScript types and exports

Build docs developers (and LLMs) love

Get started for freeTalk to us