Overview
Mintlify Components is built with Tailwind CSS v4 and uses utility-first styling. All components accept a className prop for custom styling, and the library uses clsx and tailwind-merge for efficient class composition.
Class Composition Utility
The library provides a cn utility function that combines clsx and tailwind-merge:
From packages/components/src/utils/cn.ts:1-9:
import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";
const cn = (...inputs: ClassValue[]) => {
return twMerge(clsx(inputs));
};
export { cn };
This utility intelligently merges Tailwind classes, ensuring that conflicting classes are resolved correctly. For example, cn('px-2', 'px-4') returns 'px-4'.
Styling Components
Basic Styling
All components accept a className prop:
<Card className="shadow-lg hover:shadow-xl transition-shadow">
Custom styled card
</Card>
<Badge className="font-bold uppercase" color="blue">
Custom badge
</Badge>
Responsive Styling
Use Tailwind’s responsive prefixes:
<Accordion className="mb-4 md:mb-6 lg:mb-8">
Responsive spacing
</Accordion>
<Card
className="flex-col md:flex-row gap-4 md:gap-6"
horizontal
>
Responsive layout
</Card>
Dark Mode Styling
All components support dark mode through the dark: prefix:
<div className="bg-white dark:bg-stone-900">
<h1 className="text-stone-900 dark:text-white">
Themed heading
</h1>
</div>
Component Dark Mode Patterns
From the Card component (packages/components/src/components/card/card.tsx:165-169):
className={cn(
"border border-stone-950/10 bg-white",
"dark:border-white/10 dark:bg-background-dark",
className
)}
Components use the dark: variant extensively. Make sure your application adds the dark class to the html element when dark mode is active.
Custom Utilities
Border Standard
For consistent borders:
<div className="border-standard rounded-2xl p-6">
Themed border that adapts to light/dark mode
</div>
Text Wrapping
For better text handling:
<div className="overflow-wrap-anywhere">
HandlesLongUnbrokenStringsSafely
</div>
<div className="scrollbar-common h-64 overflow-auto">
Content with custom scrollbar
</div>
<pre className="scrollbar-code-dark">
<code>Syntax highlighted code</code>
</pre>
Typography Plugin
The library includes the @tailwindcss/typography plugin for prose styling:
<div className="prose dark:prose-invert">
<h1>Styled Heading</h1>
<p>Automatically styled paragraph text.</p>
<ul>
<li>List items with proper spacing</li>
</ul>
</div>
Prose in Components
Many components use the prose class internally:
From packages/components/src/components/accordion/accordion.tsx:230:
<div className="prose prose-stone dark:prose-invert mx-6 mt-2 mb-4">
{children}
</div>
When nesting components that already use prose, you may need to use not-prose to prevent double styling.
Component Data Attributes
Components expose data attributes for advanced styling:
// Tabs component
<div data-active="true" data-component-part="tab-button">
Active tab
</div>
// Badge component
<span
data-shape="pill"
data-variant="outline"
data-disabled
>
Badge
</span>
Styling with Data Attributes
/* Target active tabs */
[data-component-part="tab-button"][data-active="true"] {
@apply font-bold;
}
/* Target disabled badges */
[data-disabled] {
@apply opacity-50 cursor-not-allowed;
}
Advanced Patterns
Conditional Classes
From packages/components/src/components/badge/badge.tsx:129-143:
className={cn(
"relative inline-flex w-fit items-center font-medium",
"data-[shape='pill']:rounded-full",
"data-[variant='outline']:outline-1",
sizeVariants[size],
colorVariants[color],
isInteractive && !disabled && "cursor-pointer hover:opacity-80",
className
)}
This pattern uses both data attributes and conditional logic to apply classes dynamically.
Group Hover Effects
From packages/components/src/components/card/card.tsx:192-201:
<div className="group">
<div className="text-stone-400 group-hover:text-primary">
Changes color on parent hover
</div>
</div>
Arbitrary Values
For one-off custom values:
<div className="w-[250px] h-[calc(100vh-80px)]">
Custom dimensions
</div>
<div className="bg-[#1a1a1a] text-[rgb(255,100,50)]">
Custom colors
</div>
Layout Utilities
Flexbox
<Card className="flex flex-col gap-4 md:flex-row md:gap-6">
Responsive flex layout
</Card>
Grid
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
<Card>Item 1</Card>
<Card>Item 2</Card>
<Card>Item 3</Card>
</div>
Spacing
<div className="space-y-4">
<Card>Automatic vertical spacing</Card>
<Card>Between siblings</Card>
</div>
Color System
Component Colors
From the Badge component color variants (packages/components/src/components/badge/badge.tsx:29-48):
<Badge color="gray">Default</Badge>
<Badge color="blue">Information</Badge>
<Badge color="green">Success</Badge>
<Badge color="yellow">Warning</Badge>
<Badge color="red">Error</Badge>
<Badge color="purple">Special</Badge>
Custom Colors
Components that support custom colors:
<Callout variant="custom" color="#8b5cf6">
Custom purple callout
</Callout>
<Icon icon="star" color="#fbbf24" />
When using custom colors, the component automatically calculates appropriate contrast colors for text and borders.
Animation and Transitions
Hover Effects
<Card className="transition-all duration-300 hover:scale-105 hover:shadow-xl">
Animated card
</Card>
Focus States
From packages/components/src/components/card/card.tsx:168:
"focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary"
Always include focus states for interactive components to maintain accessibility.
Code Syntax Highlighting
The library includes special styling for code blocks:
From packages/components/src/code.css:
/* Inline code */
:not(pre) > code {
@apply wrap-break-word rounded-md px-2 py-0.5
text-stone-600 dark:text-stone-200
bg-stone-100/50 dark:bg-white/5;
}
/* Code blocks with line numbers */
.has-line-numbers pre.shiki > code > .line::before {
content: counter(step);
counter-increment: step;
width: 0.6rem;
margin-right: 1.1rem;
}
Best Practices
PostCSS Configuration
The library uses PostCSS with the Tailwind plugin:
From packages/components/postcss.config.js:1-6:
export default {
plugins: {
"@tailwindcss/postcss": {},
},
};
Make sure your application has a similar PostCSS configuration to process Tailwind CSS correctly.
Next Steps