Building Interactive Components with MDX

MDX is a powerful format that allows you to seamlessly blend Markdown with React components, creating rich, interactive content that goes far beyond traditional blog posts.

What Makes MDX Special?

MDX combines the simplicity of Markdown with the power of React, allowing you to:

📝 Write in Markdown - Use familiar syntax for content
⚛️ Embed React Components - Add interactivity and rich UI
🎨 Custom Styling - Full control over presentation
🔧 Reusable Components - Build once, use everywhere

Interactive Examples

Custom Buttons

Here's how you can embed interactive components directly in your content:

Rich Cards

You can create sophisticated layouts using your component library:

🚀 Feature Highlight

This card is rendered using our custom Card components right inside MDX!

The content here can include any formatting, bold text, italic text, and even

links

MDX Powered

Code Examples with Syntax Highlighting

With Expressive Code, your code blocks get beautiful syntax highlighting and enhanced features:

// Example React component with enhanced highlighting
function MyComponent({ title }: { title: string }) {
  const [isVisible, setIsVisible] = useState(true);

  const handleToggle = () => {
    setIsVisible(!isVisible);
  };

  return (
    <div className='rounded-lg border p-4'>
      <h2 className='text-xl font-bold'>{title}</h2>
      {isVisible && <p>This is a custom component!</p>}
      <button onClick={handleToggle}>{isVisible ? 'Hide' : 'Show'} Content</button>
    </div>
  );
}

You can also highlight specific lines and add titles to your code blocks:

# Install dependencies with bun
bun add rehype-expressive-code

# Start development server
bun run dev

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "Old description",
  "description": "New and improved description",
  "scripts": {
    "dev": "next dev"
  }
}

You can also show inline code like useState or useEffect.

Advanced Layouts

Multi-Column Content

Column 1

This demonstrates how you can create complex layouts by combining MDX with Tailwind CSS classes.

Column 2

Each card can contain different content, making your blog posts more visually interesting and engaging.

Alert Boxes

⚠️

Pro Tip

You can create custom alert components and use them throughout your MDX content for better user experience.

Best Practices

1. Keep Components Simple

When creating components for MDX, focus on:

Single responsibility - Each component should do one thing well
Clear props - Make the API intuitive
Responsive design - Ensure components work on all devices

2. Maintain Readability

Even with React components, your MDX should remain readable:

<!-- Good: Clear and readable -->

<Button variant='primary'>Subscribe to Newsletter</Button>

<!-- Avoid: Too complex for content -->

<ComplexForm fields={[...manyFields]} validation={complexValidation} onSubmit={handleComplexSubmit} />

3. Performance Considerations

Use server components when possible
Lazy load heavy interactive components
Keep bundle size in mind

Integration with Your Stack

Tailwind CSS

MDX works seamlessly with Tailwind:

Beautiful Gradients

You can apply any Tailwind classes directly to your JSX elements.

TypeScript Support

All your components get full TypeScript support:

interface BlogCardProps {
  title: string;
  description?: string;
  featured?: boolean;
}

function BlogCard({ title, description, featured = false }: BlogCardProps) {
  return (
    <Card className={featured ? 'border-primary' : ''}>
      <CardHeader>
        <CardTitle>{title}</CardTitle>
        {description && <CardDescription>{description}</CardDescription>}
      </CardHeader>
    </Card>
  );
}

Enhanced Code Features

Code Diffs and Annotations

Expressive Code allows you to show code changes and add annotations:

import { useState } from 'react';

// Custom hook for counter functionality
export function useCounter(initialValue = 0) {
  const [count, setCount] = useState(initialValue);
  const [value, setValue] = useState(initialValue); // Old way

  const increment = () => setCount(count + 1);
  const decrement = () => setCount(count - 1);
  const reset = () => setCount(initialValue);

  return { count, increment, decrement, reset };
}

Multiple File Tabs

You can even show multiple related files:

import { useCounter } from '@/hooks/useCounter';

export function Counter() {
  const { count, increment, decrement, reset } = useCounter(0);

  return (
    <div className='flex items-center gap-4'>
      <button onClick={decrement}>-</button>
      <span className='text-xl font-bold'>{count}</span>
      <button onClick={increment}>+</button>
      <button onClick={reset}>Reset</button>
    </div>
  );
}

import { Counter } from '@/components/Counter';

export default function Home() {
  return (
    <main className='p-8'>
      <h1>Counter Demo</h1>
      <Counter />
    </main>
  );
}

Code Frames with Copy Button

Every code block automatically gets a copy button and proper syntax highlighting:

/* Custom component styles */
.button {
  @apply inline-flex items-center justify-center rounded-md;
  @apply px-4 py-2 text-sm font-medium;
  @apply transition-colors focus-visible:outline-none;
  @apply focus-visible:ring-ring focus-visible:ring-2;
  @apply disabled:pointer-events-none disabled:opacity-50;
}

.button-primary {
  @apply bg-primary text-primary-foreground;
  @apply hover:bg-primary/90;
}

.button-secondary {
  @apply bg-secondary text-secondary-foreground;
  @apply hover:bg-secondary/80;
}

Real-World Use Cases

Documentation

MDX is perfect for technical documentation where you need to show live examples:

API Reference

Here's how to use our Button component:

Interactive Tutorials

Create step-by-step guides with interactive elements:

Step 1: Install Dependencies

bun add @next/mdx @mdx-js/react

Step 2: Configure Next.js

Update your next.config.js file...

Conclusion

MDX opens up endless possibilities for creating rich, interactive content. By combining the simplicity of Markdown with the power of React components, you can create blog posts that truly engage your readers.

Ready to Get Started?

Start building amazing interactive content with MDX today!

Explore More Posts

Learn MDX

This post was written entirely in MDX, demonstrating the seamless integration of Markdown content with React components. Pretty cool, right?