Skip to main content

​
Frequently Asked Questions

Find answers to common questions about using the components library.

​
Installation & Setup

Install the package using your preferred package manager:
npm install @mintlify/components
or
pnpm add @mintlify/components
or
yarn add @mintlify/components
The components library requires:
  • Node.js 16.x or higher
  • React 18.x or higher
  • Tailwind CSS 3.x or 4.x
Yes, you’ll need to:
  1. Import the CSS in your main app file: 
    import '@mintlify/components/styles.css';
  2. Ensure Tailwind CSS is properly configured in your project.

​
Tailwind CSS

The components library supports both Tailwind CSS v3 and v4:
  • Tailwind v3: Uses the classic configuration approach with tailwind.config.js
  • Tailwind v4: Supports the new CSS-first configuration with @theme directives
Both versions work seamlessly with the components. The library uses canonical Tailwind classes that are compatible with both versions.
You can override component styles by:
  1. Using custom CSS classes via the className prop on most components
  2. Modifying your Tailwind configuration to extend the theme
  3. Using CSS custom properties for deeper customization
Refer to the README for detailed style override instructions.

​
TypeScript

Yes! The library is built with TypeScript and includes full type definitions. All components are fully typed, providing excellent IDE autocomplete and type checking.
Common solutions:
  • Ensure you’re using TypeScript 4.5 or higher
  • Check that your tsconfig.json includes "moduleResolution": "node" or "bundler"
  • Verify that type exports are properly configured (fixed in v1.0.1)
  • Try clearing your TypeScript cache and rebuilding

​
Dark Mode

The components respect your Tailwind CSS dark mode configuration. To enable dark mode:
  1. Set up dark mode in your tailwind.config.js: 
    module.exports = {
  darkMode: 'class', // or 'media'
  // ...
}
  2. Toggle the dark class on your root element or use system preferences with media strategy.
Components will automatically adapt to dark mode using Tailwind’s dark mode utilities.
Yes! Extend your Tailwind theme configuration to customize colors for both light and dark modes. Components use semantic color classes that inherit from your theme.

​
Theming

Custom theming can be achieved through:
  1. Tailwind theme extension: Modify colors, spacing, and other design tokens in your Tailwind config
  2. CSS custom properties: Override component-specific CSS variables
  3. Component props: Many components accept className for custom styling
Yes! Configure custom fonts in your Tailwind configuration under theme.fontFamily. Components will inherit the font styles from your global configuration.

​
Troubleshooting

Common issues:
  • Missing CSS import: Ensure you’ve imported @mintlify/components/styles.css
  • Tailwind not configured: Verify Tailwind CSS is properly set up in your project
  • CSS bundling issues: If using v1.0.0, upgrade to v1.0.1 or later which includes the @tailwindcss/cli dependency fix
  • Build cache: Try clearing your build cache and rebuilding
If syntax highlighting isn’t working:
  • Ensure you’re on v1.0.3 or later (Shiki worker bundling was fixed in this version)
  • Check that the language prop is correctly specified on your CodeBlock component
  • Verify your bundler configuration supports web workers
For icon rendering issues:
  • Check that brand icons are using the correct format (mask-size fix in v1.0.5)
  • Ensure icon names match the supported icon set
  • Verify that icon assets are being bundled correctly
If Mermaid diagrams have issues:
  • Upgrade to v1.0.2 or later for duplicate ID fixes
  • Check that your Mermaid syntax is valid
  • Verify that the Mermaid component is properly imported
  • For gantt charts, ensure proper sizing configuration (default sizing improved in v1.0.2)
If you need additional support:
  • Check the component documentation for detailed usage examples
  • Review the changelog for recent fixes and updates
  • Open an issue on GitHub with a minimal reproduction
  • Ensure you’re using the latest version of the library

Build docs developers (and LLMs) love

Get started for freeTalk to us