react-markdown

[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]

React component to render markdown.

Feature highlights

* [x] [safe][section-security] by default
(no dangerouslySetInnerHTML or XSS attacks)
* [x] [components][section-components]
(pass your own component to use instead of

for ## hi)
* [x] [plugins][section-plugins]
(many plugins you can pick and choose from)
* [x] [compliant][section-syntax]
(100% to CommonMark, 100% to GFM with a plugin)

Contents

* What is this?
* When should I use this?
* Install
* Use
* API
* Markdown
* MarkdownAsync
* MarkdownHooks
* defaultUrlTransform(url)
* AllowElement
* Components
* ExtraProps
* HooksOptions
* Options
* UrlTransform
* Examples
* Use a plugin
* Use a plugin with options
* Use custom components (syntax highlight)
* Use remark and rehype plugins (math)
* Plugins
* Syntax
* Compatibility
* Architecture
* Appendix A: HTML in markdown
* Appendix B: Components
* Appendix C: line endings in markdown (and JSX)
* Security
* Related
* Contribute
* License

What is this?

This package is a [React][] component that can be given a string of markdown
that it’ll safely render to React elements.
You can pass plugins to change how markdown is transformed and pass components
that will be used instead of normal HTML elements.

* to learn markdown, see this [cheatsheet and tutorial][commonmark-help]
* to try out react-markdown, see [our demo][github-io-react-markdown]

When should I use this?

There are other ways to use markdown in React out there so why use this one?
The three main reasons are that they often rely on dangerouslySetInnerHTML,
have bugs with how they handle markdown, or don’t let you swap elements for
components.
react-markdown builds a virtual DOM, so React only replaces what changed,
from a syntax tree.
That’s supported because we use [unified][github-unified],
specifically [remark][github-remark] for markdown and [rehype][github-rehype]
for HTML,
which are popular tools to transform content with plugins.

This package focusses on making it easy for beginners to safely use markdown in
React.
When you’re familiar with unified, you can use a modern hooks based alternative
[react-remark][github-react-remark] or [rehype-react][github-rehype-react]
manually.
If you instead want to use JavaScript and JSX inside markdown files, use
[MDX][github-mdx].

Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][npm-install]:

``sh
npm install react-markdown
`

In Deno with [esm.sh][esmsh]:

`js
import Markdown from 'https://esm.sh/react-markdown@10'
`

In browsers with [esm.sh][esmsh]:

`html

`

Use

A basic hello world:

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

const markdown = '# Hi, Pluto!'

createRoot(document.body).render({markdown})
`

Here is an example that shows how to use a plugin
([remark-gfm][github-remark-gfm],
which adds support for footnotes, strikethrough, tables, tasklists and
URLs directly):

`js
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}
)
`

API

This package exports the identifiers
[MarkdownAsync][api-markdown-async],
[MarkdownHooks][api-markdown-hooks],
and
[defaultUrlTransform][api-default-url-transform].
The default export is [Markdown][api-markdown].

It also exports the additional [TypeScript][] types
[AllowElement][api-allow-element],
[Components][api-components],
[ExtraProps][api-extra-props],
[HooksOptions][api-hooks-options],
[Options][api-options],
and
[UrlTransform][api-url-transform].

$3

Component to render markdown.

This is a synchronous component.
When using async plugins,
see [MarkdownAsync][api-markdown-async] or
[MarkdownHooks][api-markdown-hooks].

###### Parameters

* options ([Options][api-options])
— props

###### Returns

React element (ReactElement).

$3

Component to render markdown with support for async plugins
through async/await.

Components returning promises are supported on the server.
For async support on the client,
see [MarkdownHooks][api-markdown-hooks].

###### Parameters

* options ([Options][api-options])
— props

###### Returns

Promise to a React element (Promise).

$3

Component to render markdown with support for async plugins through hooks.

This uses useEffect and useState hooks.
Hooks run on the client and do not immediately render something.
For async support on the server,
see [MarkdownAsync][api-markdown-async].

###### Parameters

* options ([Options][api-options])
— props

###### Returns

React node (ReactNode).

$3

Make a URL safe.

###### Parameters

* url (string)
— URL

###### Returns

Safe URL (string).

$3

Filter elements (TypeScript type).

###### Parameters

* node ([Element from hast][github-hast-element])
— element to check
* index (number | undefined)
— index of element in parent
* parent ([Node from hast][github-hast-nodes])
— parent of element

###### Returns

Whether to allow element (boolean, optional).

$3

Map tag names to components (TypeScript type).

###### Type

`ts
import type {ExtraProps} from 'react-markdown'
import type {ComponentProps, ElementType} from 'react'

type Components = {
[Key in Extract]?: ElementType & ExtraProps>
}
`

$3

Extra fields we pass to components (TypeScript type).

###### Fields

* node ([Element from hast][github-hast-element], optional)
— original node

$3

Configuration for [MarkdownHooks][api-markdown-hooks] (TypeScript type);
extends the regular [Options][api-options] with a fallback prop.

###### Extends

[Options][api-options].

###### Fields

* fallback (ReactNode, optional)
— content to render while the processor processing the markdown

$3

Configuration (TypeScript type).

###### Fields

* allowElement ([AllowElement][api-allow-element], optional)
— filter elements;
allowedElements / disallowedElements is used first
* allowedElements (Array, default: all tag names)
— tag names to allow;
cannot combine w/ disallowedElements
* children (string, optional)
— markdown
* components ([Components][api-components], optional)
— map tag names to components
* disallowedElements (Array, default: [])
— tag names to disallow;
cannot combine w/ allowedElements
* rehypePlugins (Array, optional)
— list of [rehype plugins][github-rehype-plugins] to use
* remarkPlugins (Array, optional)
— list of [remark plugins][github-remark-plugins] to use
* remarkRehypeOptions
([Options from remark-rehype][github-remark-rehype-options],
optional)
— options to pass through to remark-rehype
* skipHtml (boolean, default: false)
— ignore HTML in markdown completely
* unwrapDisallowed (boolean, default: false)
— extract (unwrap) what’s in disallowed elements;
normally when say strong is not allowed, it and it’s children are dropped,
with unwrapDisallowed the element itself is replaced by its children
* urlTransform ([UrlTransform][api-url-transform], default:
[defaultUrlTransform][api-default-url-transform])
— change URLs

$3

Transform URLs (TypeScript type).

###### Parameters

* url (string)
— URL
* key (string, example: 'href')
— property name
* node ([Element from hast][github-hast-element])
— element to check

###### Returns

Transformed URL (string, optional).

Examples

$3

This example shows how to use a remark plugin.
In this case, [remark-gfm][github-remark-gfm],
which adds support for strikethrough, tables, tasklists and URLs directly:

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

const markdown = A paragraph with emphasis and strong importance.

> A block quote with ~strikethrough~ and a URL: https://reactjs.org.

* Lists
* [ ] todo
* [x] done

A table:

| a | b |
| - | - |

createRoot(document.body).render(
{markdown}
)
`

$3

This example shows how to use a plugin and give it options.
To do that, use an array with the plugin at the first place, and the options
second.
[remark-gfm][github-remark-gfm] has an option to allow only double tildes for
strikethrough:

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

const markdown = 'This ~is not~ strikethrough, but ~~this is~~!'

createRoot(document.body).render(

{markdown}

)
`

$3

This example shows how you can overwrite the normal handling of an element by
passing a component.
In this case, we apply syntax highlighting with the seriously super amazing
[react-syntax-highlighter][github-react-syntax-highlighter] by
[@conorhastings][github-conorhastings]:

`js
import React from 'react'
import {createRoot} from 'react-dom/client'
import Markdown from 'react-markdown'
import {Prism as SyntaxHighlighter} from 'react-syntax-highlighter'
import {dark} from 'react-syntax-highlighter/dist/esm/styles/prism'

// Did you know you can use tildes instead of backticks for code in markdown? ✨
const markdown = Here is some JavaScript code:

~~~js
console.log('It works!')
~~~

createRoot(document.body).render(
children={markdown}
components={{
code(props) {
const {children, className, node, ...rest} = props
const match = /language-(\w+)/.exec(className || '')
return match ? (
{...rest}
PreTag="div"
children={String(children).replace(/\n$/, '')}
language={match[1]}
style={dark}
/>
) : (

{children}

)
}
}}
/>
)
`

$3

This example shows how a syntax extension
(through [remark-math][github-remark-math])
is used to support math in markdown, and a transform plugin
([rehype-katex][github-rehype-katex]) to render that math.

`js
import React from 'react'
import {createRoot} from 'react-dom/client'
import Markdown from 'react-markdown'
import rehypeKatex from 'rehype-katex'
import remarkMath from 'remark-math'
import 'katex/dist/katex.min.css' // rehype-katex does not import the CSS for you

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

createRoot(document.body).render(

{markdown}

)
`

Plugins

We use [unified][github-unified],
specifically [remark][github-remark] for markdown and
[rehype][github-rehype] for HTML,
which are tools to transform content with plugins.
Here are three good ways to find plugins:

* [awesome-remark][github-awesome-remark] and
[awesome-rehype][github-awesome-rehype]
— selection of the most awesome projects
* [List of remark plugins][github-remark-plugins] and
[list of rehype plugins][github-rehype-plugins]
— list of all plugins
* [remark-plugin][github-topic-remark-plugin] and
[rehype-plugin][github-topic-rehype-plugin] topics
— any tagged repo on GitHub

Syntax

react-markdown follows CommonMark, which standardizes the differences between
markdown implementations, by default.
Some syntax extensions are supported through plugins.

We use [micromark][github-micromark] under the hood for our parsing.
See its documentation for more information on markdown, CommonMark, and
extensions.

Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, react-markdown@10,
compatible with Node.js 16.

They work in all modern browsers (essentially: everything not IE 11).
You can use a bundler (such as esbuild, webpack, or Rollup) to use this package
in your project, and use its options (or plugins) to add support for legacy
browsers.

Architecture

                                                           react-markdown
         +----------------------------------------------------------------------------------------------------------------+
         |                                                                                                                |
         |  +----------+        +----------------+        +---------------+       +----------------+       +------------+ |
         |  |          |        |                |        |               |       |                |       |            | |
markdown-+->+  remark  +-mdast->+ remark plugins +-mdast->+ remark-rehype +-hast->+ rehype plugins +-hast->+ components +-+->react elements
         |  |          |        |                |        |               |       |                |       |            | |
         |  +----------+        +----------------+        +---------------+       +----------------+       +------------+ |
         |                                                                                                                |
         +----------------------------------------------------------------------------------------------------------------+

To understand what this project does, it’s important to first understand what
unified does: please read through the [unifiedjs/unified][github-unified]
readme
(the part until you hit the API section is required reading).

react-markdown is a unified pipeline — wrapped so that most folks don’t need
to directly interact with unified.
The processor goes through these steps:

* parse markdown to mdast (markdown syntax tree)
* transform through remark (markdown ecosystem)
* transform mdast to hast (HTML syntax tree)
* transform through rehype (HTML ecosystem)
* render hast to React with components

Appendix A: HTML in markdown

react-markdown typically escapes HTML (or ignores it, with skipHtml)
because it is dangerous and defeats the purpose of this library.

However, if you are in a trusted environment (you trust the markdown), and
can spare the bundle size (±60kb minzipped), then you can use
[rehype-raw][github-rehype-raw]:

`js
import React from 'react'
import {createRoot} from 'react-dom/client'
import Markdown from 'react-markdown'
import rehypeRaw from 'rehype-raw'

const markdown =

createRoot(document.body).render(
{markdown}
)
`

Note: HTML in markdown is still bound by how [HTML works in
CommonMark][commonmark-html].
Make sure to use blank lines around block-level HTML that again contains
markdown!

Appendix B: Components

You can also change the things that come from markdown:

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

The keys in components are HTML equivalents for the things you write with
markdown (such as h1 for # heading).
Normally, in markdown, those are: a, blockquote, br, code, em, h1,
h2, h3, h4, h5, h6, hr, img, li, ol, p, pre, strong, and
ul.
With [remark-gfm][github-remark-gfm],
you can also use del, input, table, tbody, td, th, thead, and tr.
Other remark or rehype plugins that add support for new constructs will also
work with react-markdown.

The props that are passed are what you probably would expect: an a (link) will
get href (and title) props, and img (image) an src, alt and title,
etc.

Every component will receive a node.
This is the original [Element from hast][github-hast-element] element being
turned into a React element.

Appendix C: line endings in markdown (and JSX)

You might have trouble with how line endings work in markdown and JSX.
We recommend the following, which solves all line ending problems:

`js
// If you write actual markdown in your code, put your markdown in a variable;
// do not indent markdown:
const markdown =

This is perfect!