Integrating React in MDX

The Power of MDX: Markdown + JSX

The name "MDX" is a portmanteau of "Markdown" and "JSX". While you've used these technologies separately, MDX allows you to use them together in the same file. This means you can write standard Markdown for your articles and, whenever you need something more complex than static text or images, you can seamlessly drop in a fully-featured component.

Just like in a standard JavaScript or TypeScript file, you can use import statements at the top of your .mdx file. This allows you to bring in components from your project's src/components/ directory and use them as if they were custom HTML tags.

Let's start by looking at the official Astro documentation, which gives a concise overview of this capability.

Bridging the Gap: The client: Directive

As the documentation highlights, using a framework component like one from React requires a special piece of Astro syntax: the client:directive.

This is a critical concept. By default, Astro renders everything to static HTML and ships zero client-side JavaScript. This is why Astro sites are so fast. When you use a plain Astro component or standard Markdown, there's no interactivity, so no JavaScript is needed.

However, a React component with state (useState) or effects (useEffect) needs JavaScript to run in the user's browser to become interactive. The client: directive is your way of telling Astro, "This specific component is an interactive island. Please hydrate it by sending its JavaScript to the client."

There are several client directives, which we'll explore more in a later module, but the most common one to start with is client:load. This tells Astro to load and hydrate the component as soon as the page loads.

Practical Example: Adding an Interactive CTA

Let's build a practical example relevant to our accounting website. A common feature within a blog post or service page is a "Call to Action" (CTA) to encourage users to get in touch. We can build this as a reusable, interactive React component.

Step 1: Create the React Component

First, make sure you have the React integration installed in your Astro project. If you don't, you can add it by running this command in your terminal:
npx astro add react

Now, let's create our component. In your src/components/ directory, create a new file named InteractiveCTA.jsx.

// src/components/InteractiveCTA.jsx
import React, { useState } from 'react';

// A simple hook for styling, you can make this more robust with CSS modules or styled-components
const buttonStyles = {
  backgroundColor: '#005f73',
  color: 'white',
  padding: '12px 24px',
  border: 'none',
  borderRadius: '5px',
  cursor: 'pointer',
  fontSize: '1rem',
  fontWeight: 'bold',
  transition: 'background-color 0.3s ease',
};

const InteractiveCTA = ({ message = "Ready to optimize your finances?" }) => {
  const [clicked, setClicked] = useState(false);

  const handleClick = () => {
    setClicked(true);
    // In a real app, this could trigger a modal, scroll to a contact form, etc.
    alert("Great! Let's connect. You will be redirected to our contact page.");
  };

  return (
    <div style={{ padding: '2rem', border: '1px solid #e0e0e0', borderRadius: '8px', textAlign: 'center', margin: '2rem 0' }}>
      <p style={{ margin: '0 0 1rem 0', fontSize: '1.2rem' }}>{message}</p>
      <button 
        style={buttonStyles}
        onClick={handleClick}
        disabled={clicked}
        onMouseOver={e => e.currentTarget.style.backgroundColor = '#0a9396'}
        onMouseOut={e => e.currentTarget.style.backgroundColor = '#005f73'}
      >
        {clicked ? "Thank You!" : "Request a Free Consultation"}
      </button>
    </div>
  );
};

export default InteractiveCTA;

This is a standard React component. It uses the useState hook to manage its state, making it interactive.

Step 2: Embed the Component in MDX

Now, let's open one of our content files, for example, src/content/blog/understanding-tax-deductions.mdx. We can now import and use our new component.

---
title: "A Beginner's Guide to Tax Deductions"
description: "Learn the basics of tax deductions for small businesses and individuals to maximize your savings."
pubDate: "2024-08-15"
category: "Tax"
tags: ["small business", "tax tips", "individuals"]
isDraft: false
heroImage: "/images/blog/tax-deductions-hero.jpg"
---
import InteractiveCTA from '../../components/InteractiveCTA.jsx';

# A Beginner's Guide to Tax Deductions

Welcome to our guide on understanding tax deductions! For many small business owners and individuals, navigating the world of taxes can be daunting.

... (rest of the article content) ...

## Ready to Take the Next Step?

Understanding your taxes is the first step. The next is taking action.

<InteractiveCTA client:load />

Our team of experts is here to help you navigate the complexities of tax law and ensure you're making the most of every available deduction.

That's it! Notice the three key parts:

1. import InteractiveCTA from '../../components/InteractiveCTA.jsx';: We import the component just like in any JS file.
2. <InteractiveCTA />: We use it like a custom HTML tag.
3. client:load: We tell Astro this is an interactive island that needs its JavaScript in the browser.

The following blog post offers another perspective and reinforces this concept with more examples.

import React, { useState } from 'react';

const TipCalculator = () => {
  const [bill, setBill] = useState('');
  const [tip, setTip] = useState(null);

  const calculateTip = () => {
    const billAmount = parseFloat(bill);
    if (!isNaN(billAmount) && billAmount > 0) {
      const tipAmount = (billAmount * 0.15).toFixed(2);
      setTip(tipAmount);
    } else {
      setTip(null);
      alert('Please enter a valid bill amount.');
    }
  };

  return (
    <div style={{ border: '1px solid #ccc', padding: '16px', borderRadius: '8px' }}>
      <h4>Quick Tip Calculator</h4>
      <input 
        type="number"
        value={bill}
        onChange={(e) => setBill(e.target.value)}
        placeholder="Enter bill amount"
        style={{ padding: '8px', marginRight: '8px' }}
      />
      <button onClick={calculateTip} style={{ padding: '8px 12px' }}>Calculate 15% Tip</button>
      {tip !== null && (
        <p style={{ marginTop: '12px', fontWeight: 'bold' }}>
          Tip to add: ${tip}
        </p>
      )}
    </div>
  );
};

export default TipCalculator;

---
title: "Tips for Managing Business Expenses"
// ... other frontmatter
---
import TipCalculator from '../../components/TipCalculator.jsx';

# Managing Business Expenses

When dining with clients, it's important to keep track of all expenses, including tips. Here's a handy calculator to help you out.

<TipCalculator client:load />

Remember to always keep your receipts for tax purposes...

Conclusion

You have now connected your React skills directly to Astro's content engine. This is a fundamental pattern for building modern, content-rich websites. You can maintain the performance benefits of a static site while introducing highly interactive, client-side applications exactly where you need them.

Key Takeaways:

• MDX allows you to import and use components (both Astro and UI frameworks like React) directly inside your Markdown content.
• To make a React component interactive, you must use a client:* directive (e.g., client:load) to hydrate it.
• This "island architecture" approach preserves Astro's zero-JS-by-default performance, only loading JavaScript for the specific components that need it.

You now have all the tools to create rich, individual pieces of content.

Up Next: We have our content files, complete with metadata and interactive elements. But how do we get them to show up on a central "Blog" page? In the next lesson, you will learn how to query and filter your content collections programmatically. This is the key to building index pages, archives, and dynamically displaying lists of your content across the site.