FAQ

Frequently asked questions about installation, setup, and usage

Frequently Asked Questions

Find answers to common questions about using the components library.

Installation & Setup

How do I install the components library?

Install the package using your preferred package manager:

npm install @mintlify/components

or

pnpm add @mintlify/components

or

yarn add @mintlify/components

What are the system requirements?

The components library requires:

• Node.js 16.x or higher
• React 18.x or higher
• Tailwind CSS 3.x or 4.x

Do I need to configure anything after installation?

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

What's the difference between Tailwind v3 and v4 support?

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.

How do I customize Tailwind styles for components?

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

Does the library support 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.

I'm getting type errors. What should I do?

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

How do I enable 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.

Can I customize dark mode colors?

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

How do I apply custom themes?

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

Can I use custom fonts?

Yes! Configure custom fonts in your Tailwind configuration under theme.fontFamily. Components will inherit the font styles from your global configuration.

Troubleshooting

Components aren't styled correctly. What's wrong?

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

Code blocks aren't rendering with syntax highlighting

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

Icons aren't displaying properly

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

Mermaid diagrams aren't rendering

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)

Where can I get help?

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