react-markdown

react-markdown is a unified pipeline that processes content through several stages:

1. Parse: Markdown is parsed into an mdast (markdown syntax tree).
2. Transform (Markdown): The mdast is transformed using remark plugins.
3. Convert: The mdast is converted into a hast (HTML syntax tree) via remark-rehype.
4. Transform (HTML): The hast is transformed using rehype plugins.
5. Render: The hast is rendered into React elements using the components mapping.

Use rehypePlugins to apply transformations to the HTML syntax tree (hast). A common use case is rendering math using remark-math for syntax extension and rehype-katex for HTML transformation.

import Markdown from 'react-markdown'
import rehypeKatex from 'rehype-katex'
import remarkMath from 'remark-math'
import 'katex/dist/katex.min.css'

const markdown = `The lift coefficient ($C_L$) is a dimensionless coefficient.`

<Markdown remarkPlugins={[remarkMath]} rehypePlugins={[rehypeKatex]}>
  {markdown}
</Markdown>

You can extend markdown support (e.g., for tables, tasklists, or strikethrough) by passing plugins to the remarkPlugins prop. To pass options to a plugin, use an array where the first element is the plugin function and the second is the options object.

import Markdown from 'react-markdown'
import remarkGfm from 'remark-gfm'

// Basic usage
<Markdown remarkPlugins={[remarkGfm]}>{markdown}</Markdown>

// Usage with options
<Markdown remarkPlugins={[[remarkGfm, {singleTilde: false}]]}>{markdown}</Markdown>

While react-markdown is secure by default, you can introduce vulnerabilities by:

• Overwriting urlTransform with an insecure implementation.
• Using insecure remarkPlugins, rehypePlugins, or components.

To ensure content is completely safe, especially when using plugins, it is recommended to use rehype-sanitize. This allows you to define a custom schema of allowed elements and attributes.

By default, react-markdown escapes or ignores HTML for security. If you trust the source and need to render raw HTML within your markdown, use the rehype-raw plugin via the rehypePlugins prop.

import Markdown from 'react-markdown'
import rehypeRaw from 'rehype-raw'

const markdown = `<div class="note">Some *emphasis*!</div>`

<Markdown rehypePlugins={[rehypeRaw]}>
  {markdown}
</Markdown>

Install react-markdown via npm for Node.js (version 16+). Note that this package is ESM only.

For Deno or browser environments, use esm.sh to import the package directly.

npm install react-markdown

You can extend markdown functionality (like GFM support) by passing plugins to the remarkPlugins prop. For example, using remark-gfm adds support for footnotes, strikethrough, tables, tasklists, and URLs.

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

const markdown = `Just a link: www.nasa.gov.`

createRoot(document.body).render(
  <Markdown remarkPlugins={[remarkGfm]}>{markdown}</Markdown>
)

You can use the components prop to map markdown elements to different HTML tags or React components. For example, you can map an h1 to an h2 tag, or wrap an em tag in a styled i tag.

<Markdown
  components={{
    // Map `h1` (`# heading`) to use `h2`s.
    h1: 'h2',
    // Rewrite `em`s (`*like so*`) to `i` with a red foreground color.
    em(props) {
      const {node, ...rest} = props
      return <i style={{color: 'red'}} {...rest} />
    }
  }}
/>

The Markdown component is a synchronous component that renders a string of markdown into React elements. It is safe by default and does not use dangerouslySetInnerHTML.

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

const markdown = '# Hi, *Pluto*!'

createRoot(document.body).render(<Markdown>{markdown}</Markdown>)