Integration Guides

Overview#

MDX UI provides beautifully designed components for your MDX content. After installing components with the CLI, you need to set up an MDX renderer to use them in your markdown files.

Prerequisites#

Before integrating MDX UI, make sure you have:

1. Installed components using the CLI
2. Tailwind CSS configured in your project
3. A Next.js project (or other React framework)

Choose Your Framework#

MDX UI works with any MDX renderer. Follow the guide for your setup:

Next.js#

Covers both @next/mdx (MDX files as pages) and next-mdx-remote (content from files or a CMS) — pick the approach that fits your project.

View Guide →

React + Vite#

For SPAs, dashboards, and interactive docs without SSR.

View Guide →

Quick Start#

Regardless of which renderer you choose, the integration follows the same pattern:

1. Install Components#

npx @ravikumarsurya/mdx-ui@latest init
npx @ravikumarsurya/mdx-ui@latest add callout headings paragraph

Available Components:

• blockquote - Styled quote blocks for citations
• callout - Alert/notice boxes with variants (info, warning, error, success)
• code-block - Syntax-highlighted code with language support
• emphasis - Bold and italic text styling
• headings - H1-H6 with anchor links and styling
• horizontal-rule - Section dividers
• image - Responsive, optimized images
• inline-code - Inline code snippets with styling
• list - Ordered and unordered lists
• paragraph - Enhanced paragraph styling
• steps - Numbered step-by-step guides
• tabs - Interactive tabbed content
• tree - File/folder tree visualization
• file-tree - Simplified file tree with string syntax

2. Create Component Mappings#

// components/mdx-components.tsx
import { H1, H2, H3 } from "@/components/mdx-ui/headings";
import { P } from "@/components/mdx-ui/paragraph";
import { Callout } from "@/components/mdx-ui/callout";
 
export const mdxComponents = {
  h1: H1,
  h2: H2,
  h3: H3,
  p: P,
  Callout,
};

3. Use in Your MDX#

# Hello World
 
This uses the custom H1 component.
 
<Callout variant="info">Custom components work too!</Callout>

Component Mappings#

All integration approaches use the same component mappings file — the CLI keeps it updated automatically.

Learn More →

Integration Guides#

• Next.js — @next/mdx or next-mdx-remote
• React + Vite — @mdx-js/rollup + MDXProvider

Coming Soon#

• Remix

Example Projects#

Check out complete working examples:

• test-app - Next.js with next-mdx-remote
• mdx-ui documentation - Next.js with contentlayer

Troubleshooting#

Components not rendering#

1. Verify you've created the component mappings file
2. Check that you're passing components={mdxComponents} to your MDX renderer
3. Ensure component names match (case-sensitive)

Styling not applied#

1. Make sure Tailwind CSS is installed
2. Configure Tailwind to scan your component directory:

// tailwind.config.ts
export default {
  content: ["./app/**/*.{ts,tsx}", "./components/**/*.{ts,tsx}"],
};

TypeScript errors#

Add path aliases to tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Need Help?#

• Browse Components
• View Examples
• Report Issues

Next Steps#

1. Choose your MDX renderer
2. Follow the integration guide
3. Start building with MDX UI!