React Markdown Component

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/react-markdown/index.js from ... not supported.

  cause `react-markdown` is an ESM-only package since v9.0.0, but your project is attempting to import it using CommonJS `require()` syntax.
  fix Change `const Markdown = require('react-markdown')` to `import Markdown from 'react-markdown'` and ensure your project is configured for ESM (e.g., by adding `"type": "module"` to `package.json` or using a bundler that handles ESM).

• TypeError: Cannot read properties of undefined (reading 'Children') (or similar React 18 related errors)

  cause You are using `react-markdown` v9.0.0 or higher with an older version of React (e.g., React 17 or earlier).
  fix Upgrade your React installation to React 18 or newer, along with its corresponding `@types/react` package. `npm install react@latest react-dom@latest @types/react@latest @types/react-dom@latest`.

• Warning: Received `true` for a non-boolean attribute `className`. If this is expected, cast the value to a string. (This warning may indicate the `className` prop is being used incorrectly with `react-markdown`).

  cause The `className` prop was removed from the main `Markdown` component in v10.0.0. Direct styling of the root element or specific child elements via `className` on the `Markdown` component is no longer supported.
  fix To apply classes or styles to specific elements rendered by `react-markdown`, use the `components` prop to override the default HTML element renderer. For example: `<Markdown components={{ p: ({node, ...props}) => <p className="my-paragraph" {...props} /> }} />`.

Warnings

• breaking The `className` prop was removed in `react-markdown` v10.0.0. Direct application of `className` to the root Markdown component is no longer supported for styling specific elements.
  Fix: To apply styles or classes to specific HTML elements, use the `components` prop. For example, to style all `h1` elements: `<Markdown components={{ h1: ({node, ...props}) => <h1 className="my-h1-class" {...props} /> }} />`.
• breaking `react-markdown` v9.0.0 and later require Node.js 16+ and React 18+ due to underlying dependency updates and API changes.
  Fix: Ensure your project's `package.json` specifies `"engines": { "node": ">=16" }` and update `react` and `@types/react` to version 18 or higher.
• breaking Starting with v9.0.0, `react-markdown` is an ESM-only package, meaning `require()` calls will no longer work.
  Fix: Migrate your import statements from `const Markdown = require('react-markdown')` to `import Markdown from 'react-markdown'` and configure your project for ESM compatibility (e.g., by setting `"type": "module"` in `package.json`).
• breaking The `transformImageUri` and `transformLinkUri` props were replaced by a single `urlTransform` prop in v9.0.0, offering a unified way to transform all URLs.
  Fix: Update your code to use the `urlTransform` prop, which takes the URL, its type ('image' or 'link'), and the value as arguments.
• gotcha While `react-markdown` is safe by default against XSS, using plugins like `rehype-raw` with untrusted markdown input can reintroduce security vulnerabilities by directly injecting raw HTML.
  Fix: Only use plugins that process raw HTML, such as `rehype-raw`, with markdown content from trusted sources, or ensure thorough sanitization of user-provided markdown before processing.

Install

• npm install react-markdown npm
• yarn add react-markdown yarn
• pnpm add react-markdown pnpm

Imports

• Markdown
  wrong:

  const Markdown = require('react-markdown')

  correct:

  import Markdown from 'react-markdown'

  The primary component for rendering markdown. `react-markdown` is ESM-only since v9.0.0.
• MarkdownHooks
  wrong:

  import MarkdownHooks from 'react-markdown'

  correct:

  import { MarkdownHooks } from 'react-markdown'

  Provides a more advanced, hook-based API for greater control over the rendering process.
• Options
  wrong:

  import { Options } from 'react-markdown'

  correct:

  import type { Options } from 'react-markdown'

  Type import for configuring the `Markdown` component's props, including plugins and component overrides.

Quickstart

Demonstrates basic usage of the `react-markdown` component to render a markdown string to React elements in a browser environment.

import React from 'react'
import {createRoot} from 'react-dom/client'
import Markdown from 'react-markdown'

const markdown = '# Hi, *Pluto*!\n\nThis is a simple example of how to use `react-markdown`.\n\n- It renders CommonMark by default.\n- You can pass plugins for GFM or other features.\n\nEnjoy rendering your markdown!'

const rootElement = document.getElementById('root') || document.createElement('div');
if (!document.getElementById('root')) {
  document.body.appendChild(rootElement);
}
const root = createRoot(rootElement);

root.render(<Markdown>{markdown}</Markdown>);