Creating Custom Components for MDX

How to build your own React components for MDX — from MDXProvider setup to overriding headings, links, and code blocks

The whole point of MDX is mixing React components into your markdown. You're not stuck with plain <h1> and <p> tags — you can replace every single HTML element with your own component, and add entirely new ones like <Steps> or <Callout>.

Here's how components work in MDX. There are three ways to get them in:

Import directly — Write import { Alert } from './Alert' at the top of an MDX file
Provide via MDXProvider — Make them available everywhere, no imports needed
Map to HTML elements — Replace what #, >, ` ``, links, etc. render as

Let's dig into each one.

MDXProvider: Global Component Registration

If you don't want authors importing stuff in every single file, use the MDXProvider. It makes components available globally:

jsx example

// app/mdx-provider.jsx (Next.js App Router)
import { MDXProvider } from '@mdx-js/react';
import { Alert } from '@/components/Alert';
import { Card, CardGrid } from '@/components/Card';
import { Tabs, TabList, Tab, TabPanel } from '@/components/Tabs';
import { Accordion, AccordionGroup } from '@/components/Accordion';
import { CodeBlock } from '@/components/CodeBlock';
import { Callout } from '@/components/Callout';
import { Steps } from '@/components/Steps';

const components = {
  // Custom components (used as <Alert>, <Card>, etc. in MDX)
  Alert,
  Card,
  CardGrid,
  Tabs,
  TabList,
  Tab,
  TabPanel,
  Accordion,
  AccordionGroup,
  CodeBlock,
  Callout,
  Steps,
};

export function MDXProviderWrapper({ children }) {
  return (
    <MDXProvider components={components}>
      {children}
    </MDXProvider>
  );
}

Next.js App Router (mdx-components.js)

Next.js 13+ has its own pattern — a special mdx-components.js file at the project root:

Example

// mdx-components.js (root of your project) import { Alert } from '@/components/Alert'; import { Card, CardGrid } from '@/components/Card'; import { CustomHeading } from '@/components/CustomHeading'; import { CustomLink } from '@/components/CustomLink'; import { CustomCode } from '@/components/CustomCode'; export function useMDXComponents(components) { return { // Custom components Alert, Card, CardGrid, // HTML element overrides h1: (props) => <CustomHeading level={1} {...props} />, h2: (props) => <CustomHeading level={2} {...props} />, h3: (props) => <CustomHeading level={3} {...props} />, a: CustomLink, code: CustomCode, // Spread any existing components ...components, }; }

Component Mapping: Overriding Default Elements

This is where things get interesting. When you write # Hello in MDX, it renders <h1>Hello</h1> by default. Component mapping lets you swap that <h1> with anything you want — a heading with auto-generated anchor links, custom fonts, whatever.

Overriding Headings

Here's a heading component that auto-generates slugs and shows a hover link:

Example

// components/CustomHeading.jsx import React from 'react'; function generateSlug(text) { return text .toString() .toLowerCase() .trim() .replace(/\s+/g, '-') .replace(/[^\w\-]+/g, '') .replace(/\-\-+/g, '-'); } export function CustomHeading({ level, children, ...props }) { const Tag = `h${level}`; const slug = generateSlug(children); const sizes = { 1: 'text-4xl font-bold mt-8 mb-4', 2: 'text-3xl font-semibold mt-8 mb-3 pb-2 border-b border-gray-200 dark:border-gray-700', 3: 'text-2xl font-semibold mt-6 mb-2', 4: 'text-xl font-medium mt-4 mb-2', 5: 'text-lg font-medium mt-3 mb-1', 6: 'text-base font-medium mt-3 mb-1', }; return ( <Tag id={slug} className={`${sizes[level]} text-gray-900 dark:text-gray-100 group`} {...props} > {children} <a href={`#${slug}`} className="ml-2 opacity-0 group-hover:opacity-100 text-blue-500 transition-opacity" aria-label={`Link to ${children}`} > # </a> </Tag> ); }

Overriding Paragraphs

jsx example

// components/CustomParagraph.jsx
export function CustomParagraph({ children, ...props }) {
  return (
    <p
      className="text-gray-700 dark:text-gray-300 leading-relaxed mb-4"
      {...props}
    >
      {children}
    </p>
  );
}

Overriding Links

This one's practical — external links get target="_blank" and a little arrow icon automatically:

jsx example

// components/CustomLink.jsx
import React from 'react';

export function CustomLink({ href, children, ...props }) {
  const isExternal = href?.startsWith('http');

  if (isExternal) {
    return (
      <a
        href={href}
        target="_blank"
        rel="noopener noreferrer"
        className="text-blue-600 dark:text-blue-400 underline hover:text-blue-800 dark:hover:text-blue-300 inline-flex items-center gap-1"
        {...props}
      >
        {children}
        <svg className="w-3 h-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" aria-hidden="true">
          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14" />
        </svg>
      </a>
    );
  }

  return (
    <a
      href={href}
      className="text-blue-600 dark:text-blue-400 underline hover:text-blue-800 dark:hover:text-blue-300"
      {...props}
    >
      {children}
    </a>
  );
}

Overriding Code Blocks

This gives you syntax highlighting with prism-react-renderer plus a copy button:

Example

// components/CustomCode.jsx import React from 'react'; import { Highlight, themes } from 'prism-react-renderer'; // Inline code export function InlineCode({ children, ...props }) { return ( <code className="px-1.5 py-0.5 bg-gray-100 dark:bg-gray-800 text-pink-600 dark:text-pink-400 rounded text-sm font-mono" {...props} > {children} </code> ); } // Code block (fenced code) export function CodeBlock({ children, className, ...props }) { const language = className?.replace('language-', '') || 'text'; const code = children?.trim() || ''; return ( <div className="relative my-4 rounded-lg overflow-hidden"> {/* Language badge */} <div className="flex items-center justify-between px-4 py-2 bg-gray-800 border-b border-gray-700"> <span className="text-xs text-gray-400 uppercase">{language}</span> <CopyButton code={code} /> </div> <Highlight code={code} language={language} theme={themes.nightOwl}> {({ className, style, tokens, getLineProps, getTokenProps }) => ( <pre className="p-4 overflow-x-auto text-sm" style={style}> {tokens.map((line, i) => ( <div key={i} {...getLineProps({ line })}> <span className="text-gray-500 mr-4 select-none text-xs"> {(i + 1).toString().padStart(2, '0')} </span> {line.map((token, key) => ( <span key={key} {...getTokenProps({ token })} /> ))} </div> ))} </pre> )} </Highlight> </div> ); } function CopyButton({ code }) { const [copied, setCopied] = React.useState(false); const handleCopy = async () => { await navigator.clipboard.writeText(code); setCopied(true); setTimeout(() => setCopied(false), 2000); }; return ( <button onClick={handleCopy} className="text-xs text-gray-400 hover:text-white transition-colors" aria-label="Copy code to clipboard" > {copied ? '✓ Copied!' : 'Copy'} </button> ); }

Overriding Blockquotes

jsx example

// components/CustomBlockquote.jsx
export function CustomBlockquote({ children, ...props }) {
  return (
    <blockquote
      className="border-l-4 border-blue-400 bg-blue-50 dark:bg-blue-900/20 pl-4 py-3 pr-4 my-4 rounded-r-lg italic text-gray-700 dark:text-gray-300"
      {...props}
    >
      {children}
    </blockquote>
  );
}

Overriding Tables

jsx example

// components/CustomTable.jsx
export function CustomTable({ children, ...props }) {
  return (
    <div className="overflow-x-auto my-4 rounded-lg border border-gray-200 dark:border-gray-700">
      <table className="w-full text-sm" {...props}>
        {children}
      </table>
    </div>
  );
}

export function CustomTh({ children, ...props }) {
  return (
    <th
      className="px-4 py-3 bg-gray-50 dark:bg-gray-800 text-left font-semibold text-gray-700 dark:text-gray-300 border-b border-gray-200 dark:border-gray-700"
      {...props}
    >
      {children}
    </th>
  );
}

export function CustomTd({ children, ...props }) {
  return (
    <td
      className="px-4 py-3 border-b border-gray-100 dark:border-gray-800 text-gray-600 dark:text-gray-400"
      {...props}
    >
      {children}
    </td>
  );
}

Complete Component Mapping

Here's the full thing — every HTML element you can override, all in one object:

Example

// components/mdx-components.js import { CustomHeading } from './CustomHeading'; import { CustomLink } from './CustomLink'; import { CustomParagraph } from './CustomParagraph'; import { InlineCode, CodeBlock } from './CustomCode'; import { CustomBlockquote } from './CustomBlockquote'; import { CustomTable, CustomTh, CustomTd } from './CustomTable'; import { CustomImage } from './CustomImage'; export const componentMapping = { // Block elements h1: (props) => <CustomHeading level={1} {...props} />, h2: (props) => <CustomHeading level={2} {...props} />, h3: (props) => <CustomHeading level={3} {...props} />, h4: (props) => <CustomHeading level={4} {...props} />, h5: (props) => <CustomHeading level={5} {...props} />, h6: (props) => <CustomHeading level={6} {...props} />, p: CustomParagraph, blockquote: CustomBlockquote, // Inline elements a: CustomLink, code: InlineCode, // Code blocks (pre > code) pre: ({ children }) => { const codeElement = children?.props; if (codeElement) { return <CodeBlock {...codeElement} />; } return <pre>{children}</pre>; }, // Tables table: CustomTable, th: CustomTh, td: CustomTd, // Images img: CustomImage, // Lists ul: (props) => <ul className="list-disc pl-6 mb-4 space-y-1 text-gray-700 dark:text-gray-300" {...props} />, ol: (props) => <ol className="list-decimal pl-6 mb-4 space-y-1 text-gray-700 dark:text-gray-300" {...props} />, li: (props) => <li className="leading-relaxed" {...props} />, // Horizontal rule hr: () => <hr className="my-8 border-gray-200 dark:border-gray-700" />, };

Wrapper Components

A wrapper wraps your *entire* MDX content. Good for adding a table of contents, reading time, navigation — stuff that goes around every page:

jsx example

// components/MDXWrapper.jsx
import React from 'react';

export function MDXWrapper({ children, meta }) {
  return (
    <article className="prose prose-lg dark:prose-invert max-w-none">
      {/* Table of contents */}
      <TableOfContents />

      {/* Reading time estimate */}
      {meta?.readingTime && (
        <p className="text-sm text-gray-500 mb-8">
          📖 {meta.readingTime} min read
        </p>
      )}

      {/* Main content */}
      <div className="mdx-content">
        {children}
      </div>

      {/* Footer navigation */}
      <DocNavigation prev={meta?.prev} next={meta?.next} />
    </article>
  );
}

jsx example

const components = {
  wrapper: MDXWrapper,
  // ... other components
};

Creating Your Own Components: Step-by-Step

Here's the workflow from idea to working component.

Step 1: Design the Component API

Think about how an author will actually write this in MDX. Keep it dead simple:

mdx example

{/* Good — clear, minimal API */}
<Steps>
  <Step title="Install dependencies">
    Run `npm install` to get started.
  </Step>
  <Step title="Configure settings">
    Create a config file with your preferences.
  </Step>
</Steps>

Step 2: Build the React Component

Example

// components/Steps.jsx import React from 'react'; export function Steps({ children }) { const steps = React.Children.toArray(children); return ( <div className="my-6 space-y-4"> {steps.map((step, index) => ( <div key={index} className="flex gap-4"> {/* Step number */} <div className="flex-shrink-0 w-8 h-8 rounded-full bg-blue-500 text-white flex items-center justify-center text-sm font-bold"> {index + 1} </div> {/* Connector line */} {index < steps.length - 1 && ( <div className="absolute left-4 top-8 bottom-0 w-0.5 bg-blue-200" /> )} {/* Step content */} <div className="flex-1 pb-4"> {step} </div> </div> ))} </div> ); } export function Step({ title, children }) { return ( <div> <h4 className="font-semibold text-gray-900 dark:text-gray-100 mb-2"> {title} </h4> <div className="text-gray-600 dark:text-gray-400"> {children} </div> </div> ); }

Step 3: Register the Component

Example

// Add to your components mapping import { Steps, Step } from '@/components/Steps'; const components = { Steps, Step, // ... existing components };

Step 4: Document the Component

Create a reference page showing usage, props, and examples (like this page!).

Design System Integration

If your team already uses Chakra UI, Material UI, Radix, etc., you can map MDX elements straight to your design system. No custom components needed.

Chakra UI Integration

Example

import { Heading, Text, Link, Code, Table, Thead, Tbody, Tr, Th, Td, UnorderedList, OrderedList, ListItem, Alert, AlertIcon, Divider, Image, } from '@chakra-ui/react'; export const chakraComponents = { h1: (props) => <Heading as="h1" size="2xl" mt={8} mb={4} {...props} />, h2: (props) => <Heading as="h2" size="xl" mt={6} mb={3} {...props} />, h3: (props) => <Heading as="h3" size="lg" mt={4} mb={2} {...props} />, p: (props) => <Text mb={4} lineHeight="tall" {...props} />, a: (props) => <Link color="blue.500" isExternal={props.href?.startsWith('http')} {...props} />, code: (props) => <Code colorScheme="pink" fontSize="sm" {...props} />, ul: (props) => <UnorderedList mb={4} spacing={1} {...props} />, ol: (props) => <OrderedList mb={4} spacing={1} {...props} />, li: (props) => <ListItem {...props} />, table: (props) => <Table variant="simple" size="sm" {...props} />, th: Th, td: Td, hr: () => <Divider my={8} />, img: Image, blockquote: (props) => ( <Alert status="info" variant="left-accent" my={4}> <AlertIcon /> <div {...props} /> </Alert> ), };

Radix UI + Tailwind Integration

Example

import * as Separator from '@radix-ui/react-separator'; import * as Tooltip from '@radix-ui/react-tooltip'; export const radixComponents = { hr: () => <Separator.Root className="my-8 h-px bg-gray-200" />, a: ({ href, children, title, ...props }) => ( <Tooltip.Provider> <Tooltip.Root> <Tooltip.Trigger asChild> <a href={href} className="text-blue-600 underline" {...props}> {children} </a> </Tooltip.Trigger> {title && ( <Tooltip.Portal> <Tooltip.Content className="bg-gray-900 text-white px-3 py-1.5 rounded text-sm"> {title} <Tooltip.Arrow className="fill-gray-900" /> </Tooltip.Content> </Tooltip.Portal> )} </Tooltip.Root> </Tooltip.Provider> ), };

Props Documentation Table for Component Mapping

Element Key	Markdown Syntax	Rendered As	Common Overrides
`h1`–`h6`	`# Heading`	`<h1>`–`<h6>`	Anchor links, custom styling
`p`	Paragraph text	`<p>`	Typography, spacing
`a`	`text`	`<a>`	External link icons, routing
`code`	` inline `	`<code>`	Syntax highlighting, copy button
`pre`	``` ``code`` ```	`<pre>`	Full code blocks with toolbars
`blockquote`	`> quote`	`<blockquote>`	Styled callouts
`ul` / `ol`	`- item` / `1. item`	`<ul>` / `<ol>`	Custom bullets, spacing
`li`	List item	`<li>`	Check marks, icons
`table`	`\	col \	`	`<table>`	Responsive wrapper, styling
`th` / `td`	Table cells	`<th>` / `<td>`	Alignment, padding
`img`	`!alt`	`<img>`	Lazy loading, captions, zoom
`hr`	`---`	`<hr>`	Custom dividers
`wrapper`	Entire document	`<div>`	Layout, table of contents

Accessibility Notes

A few things to keep in mind when you're overriding elements:

Keep semantic HTML — If you override h2, your component should still render an actual <h2> tag (or use the right ARIA role). Don't break the document outline.

External links — Tell users (and screen readers) when a link opens a new window. The icon helps visually, but add aria-label text too.

Code copy buttons — They usually just show an icon. Add an aria-label so screen readers know what the button does.

Images — Always pass through the alt text. For complex images with captions, add aria-describedby.

Tables in scroll containers — When you wrap a table in an overflow-scroll div, add role="region" and aria-label to the wrapper so screen readers announce it.

Heading hierarchy — Don't let authors skip from h2 to h5. In dev mode, you could log a warning when heading levels jump.

Advanced: Dynamic Component Loading

If you have a lot of components and don't want to bloat the bundle, load heavy ones dynamically:

Example

import dynamic from 'next/dynamic'; const components = { // Eagerly loaded (used on every page) Alert: require('@/components/Alert').Alert, // Lazily loaded (only loaded when used) Chart: dynamic(() => import('@/components/Chart').then(m => m.Chart), { loading: () => <div className="animate-pulse h-64 bg-gray-100 rounded" />, }), Mermaid: dynamic(() => import('@/components/Mermaid').then(m => m.Mermaid), { ssr: false, loading: () => <div className="animate-pulse h-48 bg-gray-100 rounded" />, }), };

Summary

Custom components are what make MDX more than just "Markdown that accepts JSX." You register components globally with MDXProvider, override default HTML elements with component mapping, and wrap pages with layout components. The trick is designing APIs that feel natural inside markdown — simple props, clear names, composable patterns. When it works well, content authors just write and the components handle styling, interactivity, and accessibility for them.

Here's how components work in MDX. There are three ways to get them in:

Import directly — Write import { Alert } from './Alert' at the top of an MDX file
Provide via MDXProvider — Make them available everywhere, no imports needed
Map to HTML elements — Replace what #, >, ` ``, links, etc. render as

Let's dig into each one.

MDXProvider: Global Component Registration

If you don't want authors importing stuff in every single file, use the MDXProvider. It makes components available globally:

jsx example

// app/mdx-provider.jsx (Next.js App Router)
import { MDXProvider } from '@mdx-js/react';
import { Alert } from '@/components/Alert';
import { Card, CardGrid } from '@/components/Card';
import { Tabs, TabList, Tab, TabPanel } from '@/components/Tabs';
import { Accordion, AccordionGroup } from '@/components/Accordion';
import { CodeBlock } from '@/components/CodeBlock';
import { Callout } from '@/components/Callout';
import { Steps } from '@/components/Steps';

const components = {
  // Custom components (used as <Alert>, <Card>, etc. in MDX)
  Alert,
  Card,
  CardGrid,
  Tabs,
  TabList,
  Tab,
  TabPanel,
  Accordion,
  AccordionGroup,
  CodeBlock,
  Callout,
  Steps,
};

export function MDXProviderWrapper({ children }) {
  return (
    <MDXProvider components={components}>
      {children}
    </MDXProvider>
  );
}

Next.js App Router (mdx-components.js)

Next.js 13+ has its own pattern — a special mdx-components.js file at the project root:

Example

Component Mapping: Overriding Default Elements

Overriding Headings

Here's a heading component that auto-generates slugs and shows a hover link:

Example

Overriding Paragraphs

jsx example

// components/CustomParagraph.jsx
export function CustomParagraph({ children, ...props }) {
  return (
    <p
      className="text-gray-700 dark:text-gray-300 leading-relaxed mb-4"
      {...props}
    >
      {children}
    </p>
  );
}

Overriding Links

This one's practical — external links get target="_blank" and a little arrow icon automatically:

jsx example

// components/CustomLink.jsx
import React from 'react';

export function CustomLink({ href, children, ...props }) {
  const isExternal = href?.startsWith('http');

  if (isExternal) {
    return (
      <a
        href={href}
        target="_blank"
        rel="noopener noreferrer"
        className="text-blue-600 dark:text-blue-400 underline hover:text-blue-800 dark:hover:text-blue-300 inline-flex items-center gap-1"
        {...props}
      >
        {children}
        <svg className="w-3 h-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" aria-hidden="true">
          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14" />
        </svg>
      </a>
    );
  }

  return (
    <a
      href={href}
      className="text-blue-600 dark:text-blue-400 underline hover:text-blue-800 dark:hover:text-blue-300"
      {...props}
    >
      {children}
    </a>
  );
}

Overriding Code Blocks

This gives you syntax highlighting with prism-react-renderer plus a copy button:

Example

Overriding Blockquotes

jsx example

// components/CustomBlockquote.jsx
export function CustomBlockquote({ children, ...props }) {
  return (
    <blockquote
      className="border-l-4 border-blue-400 bg-blue-50 dark:bg-blue-900/20 pl-4 py-3 pr-4 my-4 rounded-r-lg italic text-gray-700 dark:text-gray-300"
      {...props}
    >
      {children}
    </blockquote>
  );
}

Overriding Tables

jsx example

// components/CustomTable.jsx
export function CustomTable({ children, ...props }) {
  return (
    <div className="overflow-x-auto my-4 rounded-lg border border-gray-200 dark:border-gray-700">
      <table className="w-full text-sm" {...props}>
        {children}
      </table>
    </div>
  );
}

export function CustomTh({ children, ...props }) {
  return (
    <th
      className="px-4 py-3 bg-gray-50 dark:bg-gray-800 text-left font-semibold text-gray-700 dark:text-gray-300 border-b border-gray-200 dark:border-gray-700"
      {...props}
    >
      {children}
    </th>
  );
}

export function CustomTd({ children, ...props }) {
  return (
    <td
      className="px-4 py-3 border-b border-gray-100 dark:border-gray-800 text-gray-600 dark:text-gray-400"
      {...props}
    >
      {children}
    </td>
  );
}

Complete Component Mapping

Here's the full thing — every HTML element you can override, all in one object:

Example

Wrapper Components

A wrapper wraps your *entire* MDX content. Good for adding a table of contents, reading time, navigation — stuff that goes around every page:

jsx example

// components/MDXWrapper.jsx
import React from 'react';

export function MDXWrapper({ children, meta }) {
  return (
    <article className="prose prose-lg dark:prose-invert max-w-none">
      {/* Table of contents */}
      <TableOfContents />

      {/* Reading time estimate */}
      {meta?.readingTime && (
        <p className="text-sm text-gray-500 mb-8">
          📖 {meta.readingTime} min read
        </p>
      )}

      {/* Main content */}
      <div className="mdx-content">
        {children}
      </div>

      {/* Footer navigation */}
      <DocNavigation prev={meta?.prev} next={meta?.next} />
    </article>
  );
}

jsx example

const components = {
  wrapper: MDXWrapper,
  // ... other components
};

Creating Your Own Components: Step-by-Step

Here's the workflow from idea to working component.

Step 1: Design the Component API

Think about how an author will actually write this in MDX. Keep it dead simple:

mdx example

{/* Good — clear, minimal API */}
<Steps>
  <Step title="Install dependencies">
    Run `npm install` to get started.
  </Step>
  <Step title="Configure settings">
    Create a config file with your preferences.
  </Step>
</Steps>

Step 2: Build the React Component

Example

Step 3: Register the Component

Example

// Add to your components mapping import { Steps, Step } from '@/components/Steps'; const components = { Steps, Step, // ... existing components };

Step 4: Document the Component

Create a reference page showing usage, props, and examples (like this page!).

Design System Integration

If your team already uses Chakra UI, Material UI, Radix, etc., you can map MDX elements straight to your design system. No custom components needed.

Chakra UI Integration

Example

Radix UI + Tailwind Integration

Example

Props Documentation Table for Component Mapping

Element Key	Markdown Syntax	Rendered As	Common Overrides
`h1`–`h6`	`# Heading`	`<h1>`–`<h6>`	Anchor links, custom styling
`p`	Paragraph text	`<p>`	Typography, spacing
`a`	`text`	`<a>`	External link icons, routing
`code`	` inline `	`<code>`	Syntax highlighting, copy button
`pre`	``` ``code`` ```	`<pre>`	Full code blocks with toolbars
`blockquote`	`> quote`	`<blockquote>`	Styled callouts
`ul` / `ol`	`- item` / `1. item`	`<ul>` / `<ol>`	Custom bullets, spacing
`li`	List item	`<li>`	Check marks, icons
`table`	`\	col \	`	`<table>`	Responsive wrapper, styling
`th` / `td`	Table cells	`<th>` / `<td>`	Alignment, padding
`img`	`!alt`	`<img>`	Lazy loading, captions, zoom
`hr`	`---`	`<hr>`	Custom dividers
`wrapper`	Entire document	`<div>`	Layout, table of contents

Accessibility Notes

A few things to keep in mind when you're overriding elements:

Keep semantic HTML — If you override h2, your component should still render an actual <h2> tag (or use the right ARIA role). Don't break the document outline.

External links — Tell users (and screen readers) when a link opens a new window. The icon helps visually, but add aria-label text too.

Code copy buttons — They usually just show an icon. Add an aria-label so screen readers know what the button does.

Images — Always pass through the alt text. For complex images with captions, add aria-describedby.

Tables in scroll containers — When you wrap a table in an overflow-scroll div, add role="region" and aria-label to the wrapper so screen readers announce it.

Heading hierarchy — Don't let authors skip from h2 to h5. In dev mode, you could log a warning when heading levels jump.

Advanced: Dynamic Component Loading

If you have a lot of components and don't want to bloat the bundle, load heavy ones dynamically:

Example

MDXProvider: Global Component Registration

Next.js App Router (mdx-components.js)

Component Mapping: Overriding Default Elements

Overriding Headings

Overriding Paragraphs

Overriding Links

Overriding Code Blocks

Overriding Blockquotes

Overriding Tables

Complete Component Mapping

Wrapper Components

Creating Your Own Components: Step-by-Step

Step 1: Design the Component API

Step 2: Build the React Component

Step 3: Register the Component

Step 4: Document the Component

Design System Integration

Chakra UI Integration

Radix UI + Tailwind Integration

Props Documentation Table for Component Mapping

Accessibility Notes

Advanced: Dynamic Component Loading

Summary

Continue learning this concept

MDXProvider: Global Component Registration

Next.js App Router (mdx-components.js)

Component Mapping: Overriding Default Elements

Overriding Headings

Overriding Paragraphs

Overriding Links

Overriding Code Blocks

Overriding Blockquotes

Overriding Tables

Complete Component Mapping

Wrapper Components

Creating Your Own Components: Step-by-Step

Step 1: Design the Component API

Step 2: Build the React Component

Step 3: Register the Component

Step 4: Document the Component

Design System Integration

Chakra UI Integration

Radix UI + Tailwind Integration

Props Documentation Table for Component Mapping

Accessibility Notes

Advanced: Dynamic Component Loading

Summary

Continue learning this concept