react-markdown
!Buildbuild-badgebuild
!Coveragecoverage-badgecoverage
!Downloadsdownloads-badgedownloads
!Sizesize-badgesize
!Sponsorssponsors-badgecollective
!Backersbackers-badgecollective
!Chatchat-badgechatReact component to render markdown.
Feature highlights
- x safesection-security by default
(no `dangerouslySetInnerHTML` or XSS attacks)
(pass your own component to use instead of `<h2>` for `## hi`)
(many plugins you can pick and choose from)
(100% to CommonMark, 100% to GFM with a plugin)
Contents
* [`Markdown`](#markdown)
* [`defaultUrlTransform(url)`](#defaulturltransformurl)
* [`AllowElement`](#allowelement)
* [`Components`](#components)
* [`ExtraProps`](#extraprops)
* [`Options`](#options)
* [`UrlTransform`](#urltransform)
* [Use a plugin](#use-a-plugin)
* [Use a plugin with options](#use-a-plugin-with-options)
* [Use custom components (syntax highlight)](#use-custom-components-syntax-highlight)
* [Use remark and rehype plugins (math)](#use-remark-and-rehype-plugins-math)
- Plugins
- Syntax
- Types
- 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 tutorialcommonmark-help
- to try out
react-markdown
, see our demodemo
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 ondangerouslySetInnerHTML
,
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, specifically remark for
markdown and 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
react-remark or rehype-react
rehype-react manually.
If you instead want to use JavaScript and JSX inside markdown files, use
MDX.Install
This package is ESM onlyesm. In Node.js (version 16+), install with npm:npm install react-markdown
In Deno with
esm.sh
esmsh:import Markdown from 'https://esm.sh/react-markdown@9'
In browsers with
esm.sh
esmsh:<script type="module">
import Markdown from 'https://esm.sh/react-markdown@9?bundle'
</script>
Use
A basic hello world: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>)
Show equivalent JSX
<h1>
Hi, <em>Pluto</em>!
</h1>
Here is an example that shows how to use a plugin (
remark-gfm
remark-gfm,
which adds support for footnotes, strikethrough, tables, tasklists and URLs
directly):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>
)
Show equivalent JSX
<p>
Just a link: <a href="http://www.nasa.gov">www.nasa.gov</a>.
</p>
API
This package exports the following identifier:defaultUrlTransform
api-default-url-transform.
The default export is Markdown
api-markdown.Markdown
Component to render markdown.Parameters
options
(Options
api-options)
— props
Returns
React element (JSX.Element
).defaultUrlTransform(url)
Make a URL safe.Parameters
url
(string
)
— URL
Returns
Safe URL (string
).AllowElement
Filter elements (TypeScript type).Parameters
— element to check
index
(number | undefined
)
— index of `element` in `parent`
parent
(Node
fromhast
hast-node)
— parent of `element`
Returns
Whether to allowelement
(boolean
, optional).Components
Map tag names to components (TypeScript type).Type
import type {Element} from 'hast'
type Components = Partial<{
[TagName in keyof JSX.IntrinsicElements]:
// Class component:
| (new (props: JSX.IntrinsicElements[TagName] & ExtraProps) => JSX.ElementClass)
// Function component:
| ((props: JSX.IntrinsicElements[TagName] & ExtraProps) => JSX.Element | string | null | undefined)
// Tag name:
| keyof JSX.IntrinsicElements
}>
ExtraProps
Extra fields we pass to components (TypeScript type).Fields
node
(Element
fromhast
hast-element, optional)
— original node
Options
Configuration (TypeScript type).Fields
allowElement
(AllowElement
api-allow-element, optional)
— filter elements;
`allowedElements` / `disallowedElements` is used first
allowedElements
(Array<string>
, default: all tag names)
— tag names to allow;
cannot combine w/ `disallowedElements`
children
(string
, optional)
— markdown
className
(string
, optional)
— wrap in a `div` with this class name
components
(Components
api-components, optional)
— map tag names to components
disallowedElements
(Array<string>
, default:[]
)
— tag names to disallow;
cannot combine w/ `allowedElements`
rehypePlugins
(Array<Plugin>
, optional)
— list of [rehype plugins][rehype-plugins] to use
remarkPlugins
(Array<Plugin>
, optional)
— list of [remark plugins][remark-plugins] to use
remarkRehypeOptions
(Options
from
`remark-rehype`][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
UrlTransform
Transform URLs (TypeScript type).Parameters
url
(string
)
— URL
key
(string
, example:'href'
)
— property name
— element to check
Returns
Transformed URL (string
, optional).Examples
Use a plugin
This example shows how to use a remark plugin. In this case,remark-gfm
remark-gfm, which adds support for strikethrough,
tables, tasklists and URLs directly: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 remarkPlugins={[remarkGfm]}>{markdown}</Markdown>
)
Show equivalent JSX
<>
<p>
A paragraph with <em>emphasis</em> and <strong>strong importance</strong>.
</p>
<blockquote>
<p>
A block quote with <del>strikethrough</del> and a URL:{' '}
<a href="https://reactjs.org">https://reactjs.org</a>.
</p>
</blockquote>
<ul className="contains-task-list">
<li>Lists</li>
<li className="task-list-item">
<input type="checkbox" disabled /> todo
</li>
<li className="task-list-item">
<input type="checkbox" disabled checked /> done
</li>
</ul>
<p>A table:</p>
<table>
<thead>
<tr>
<th>a</th>
<th>b</th>
</tr>
</thead>
</table>
</>
Use a plugin with options
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
remark-gfm has an option to allow only double tildes for
strikethrough: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 remarkPlugins={[[remarkGfm, {singleTilde: false}]]}>
{markdown}
</Markdown>
)
Show equivalent JSX
<p>
This ~is not~ strikethrough, but <del>this is</del>!
</p>
Use custom components (syntax highlight)
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 amazingreact-syntax-highlighter
react-syntax-highlighter byimport 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(
<Markdown
children={markdown}
components={{
code(props) {
const {children, className, node, ...rest} = props
const match = /language-(\w+)/.exec(className || '')
return match ? (
<SyntaxHighlighter
{...rest}
PreTag="div"
children={String(children).replace(/\n$/, '')}
language={match[1]}
style={dark}
/>
) : (
<code {...rest} className={className}>
{children}
</code>
)
}
}}
/>
)
Show equivalent JSX
<>
<p>Here is some JavaScript code:</p>
<pre>
<SyntaxHighlighter language="js" style={dark} PreTag="div" children="console.log('It works!')" />
</pre>
</>
Use remark and rehype plugins (math)
This example shows how a syntax extension (throughremark-math
remark-math)
is used to support math in markdown, and a transform plugin
(rehype-katex
rehype-katex) to render that math.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 remarkPlugins={[remarkMath]} rehypePlugins={[rehypeKatex]}>
{markdown}
</Markdown>
)
Show equivalent JSX
<p>
The lift coefficient (
<span className="katex">
<span className="katex-mathml">
<math xmlns="http://www.w3.org/1998/Math/MathML">{/* … */}</math>
</span>
<span className="katex-html" aria-hidden="true">
{/* … */}
</span>
</span>
) is a dimensionless coefficient.
</p>
Plugins
We use unified, specifically remark for markdown and rehype for HTML, which are tools to transform content with plugins. Here are three good ways to find plugins:— selection of the most awesome projects
[list of rehype plugins][rehype-plugins]
— list of all plugins
— 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
micromark under the hood for our parsing.
See its documentation for more information on markdown, CommonMark, and
extensions.Types
This package is fully typed with TypeScript. It exports the additional typesAllowElement
api-allow-element,
ExtraProps
api-extra-props,
Components
api-components,
Options
api-options, and
UrlTransform
api-url-transform.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@^9
,
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
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
import React from 'react' import {createRoot} from 'react-dom/client' import Markdown from 'react-markdown' import rehypeRaw from 'rehype-raw'
const markdown = `
Some emphasis and strong!
createRoot(document.body).render( rehypeRaw}>{markdown} )
<details>
<summary>Show equivalent JSX</summary>
```jsx
<div className="note">
<p>
Some <em>emphasis</em> and <strong>strong</strong>!
</p>
</div>
Note: HTML in markdown is still bound by how HTML works in CommonMarkcommonmark-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:<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 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
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
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:// If you write actual markdown in your code, put your markdown in a variable;
// **do not indent markdown**:
const markdown = `
# This is perfect!
`
// Pass the value as an expresion as an only child:
const result = <Markdown>{markdown}</Markdown>
👆 That works. Read on for what doesn’t and why that is.
You might try to write markdown directly in your JSX and find that it does not work:
<Markdown>
# Hi
This is **not** a paragraph.
</Markdown>
The is because in JSX the whitespace (including line endings) is collapsed to a single space. So the above example is equivalent to:
<Markdown> # Hi This is **not** a paragraph. </Markdown>
Instead, to pass markdown to
Markdown
, you can use an expression:
with a template literal:<Markdown>{`
# Hi
This is a paragraph.
`}</Markdown>
Template literals have another potential problem, because they keep whitespace (including indentation) inside them. That means that the following does not turn into a heading:
<Markdown>{`
# This is **not** a heading, it’s an indented code block
`}</Markdown>
Security
Use ofreact-markdown
is secure by default.
Overwriting urlTransform
to something insecure will open you up to XSS
vectors.
Furthermore, the remarkPlugins
, rehypePlugins
, and components
you use may
be insecure.To make sure the content is completely safe, even after what plugins do, use
rehype-sanitize
rehype-sanitize.
It lets you define your own schema of what is and isn’t allowed.Related
— JSX *in* markdown
— add support for GitHub flavored markdown support
— hook based alternative
— turn HTML into React elements
Contribute
Seecontributing.md
contributing in remarkjs/.github
health for ways
to get started.
See support.md
support for ways to get help.This project has a code of conductcoc. By interacting with this repository, organization, or community you agree to abide by its terms.