import React from 'react'
import ReactMarkdown from 'react-markdown'
import ReactDom from 'react-dom'
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 |
| - | - |
ReactDom.render(
  <ReactMarkdown children={markdown} remarkPlugins={[remarkGfm]} />,
  document.body
Show equivalent JSX
    A paragraph with <em>emphasis</em> and <strong>strong importance</strong>.
  <blockquote>




    

      A block quote with <del>strikethrough</del> and a URL:{' '}
      <a href="https://reactjs.org">https://reactjs.org</a>.
  </blockquote>
    <li>Lists</li>
      <input checked={false} readOnly={true} type="checkbox" /> todo
      <input checked={true} readOnly={true} type="checkbox" /> done
  <p>A table:</p>
  <table>
    <thead>
        <td>a</td>
        <td>b</td>
    </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 has an option to allow only double tildes for strikethrough:
import React from 'react'
import ReactMarkdown from 'react-markdown'
import ReactDom from 'react-dom'
import remarkGfm from 'remark-gfm'
ReactDom.render(
  <ReactMarkdown remarkPlugins={[[remarkGfm, {singleTilde: false}]]}>
    This ~is not~ strikethrough, but ~~this is~~!
  </ReactMarkdown>,
  document.body
Show equivalent JSX
  This ~is not~ strikethrough, but <del>this is</del>!
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 amazing
react-syntax-highlighter by
@conorhastings:
import React from 'react'
import ReactDom from 'react-dom'
import ReactMarkdown 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!')
ReactDom.render(
  <ReactMarkdown
    children={markdown}
    components={{
      code({node, inline, className, children, ...props}) {
        const match = /language-(\w+)/.exec(className || '')
        return !inline && match ? (
          <SyntaxHighlighter
            {...props}
            children={String(children).replace(/\n$/, '')}
            style={dark}
            language={match[1]}
            PreTag="div"
        ) : (
          <code {...props} className={className}>
            {children}
          </code>
  document.body
Show equivalent JSX
  <p>Here is some JavaScript code:</p>
    <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 (through remark-math)
is used to support math in markdown, and a transform plugin
(rehype-katex) to render that math.
import React from 'react'
import ReactDom from 'react-dom'
import ReactMarkdown from 'react-markdown'
import remarkMath from 'remark-math'
import rehypeKatex from 'rehype-katex'
import 'katex/dist/katex.min.css' // `rehype-katex` does not import the CSS for you
ReactDom.render(
  <ReactMarkdown
    children={`The lift coefficient ($C_L$) is a dimensionless coefficient.`}
    remarkPlugins={[remarkMath]}
    rehypePlugins={[rehypeKatex]}
  document.body
Show equivalent JSX
  The lift coefficient (
  <span className="math math-inline">
    <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>
  </span>
  ) is a dimensionless coefficient.
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:
awesome-remark and awesome-rehype
— selection of the most awesome projects
List of remark plugins and
list of rehype plugins
— list of all plugins
remark-plugin and 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 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 Options and Components types, which specify the interface of the
accepted props and components.
Compatibility
Projects maintained by the unified collective are compatible with all maintained
versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
Our projects sometimes work with older versions, but this is not guaranteed.
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 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:
import React from 'react'
import ReactDom from 'react-dom'
import ReactMarkdown from 'react-markdown'
import rehypeRaw from 'rehype-raw'
const input = `<div class="note">
Some *emphasis* and <strong>strong</strong>!
</div>`
ReactDom.render(
  <ReactMarkdown rehypePlugins={[rehypeRaw]} children={input} />,
  document.body
Show equivalent JSX
<div class="note">
  <p>Some <em>emphasis</em> and <strong>strong</strong>!</p>
</div>
Note: HTML in markdown is still bound by how HTML works in
CommonMark.
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:
<ReactMarkdown
  components={{
    // Map `h1` (`# heading`) to use `h2`s.
    h1: 'h2',
    // Rewrite `em`s (`*like so*`) to `i` with a red foreground color.
    em: ({node, ...props}) => <i style={{color: 'red'}} {...props} />
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
With 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,
There are some extra props passed.
inline (boolean?)
— set to true for inline code
className (string?)
— set to language-js or so when using ```js
style (Object?)
— something like {textAlign: 'left'} depending on how the cell is
aligned
isHeader (boolean)
— whether it’s a th or not
tr (when using remark-gfm)
isHeader (boolean)
— whether it’s in the thead or not
Every component will receive a node (Object).
This is the original hast element being
turned into a React element.
Every element will receive a key (string).
See React’s docs for more
info.
Optionally, components will also receive:
data-sourcepos (string)
— see sourcePos option
sourcePosition (Object)
— see rawSourcePos option
index and siblingCount (number)
— see includeElementIndex option
target on a (string)
— see linkTarget option
Security
Use of react-markdown is secure by default.
Overwriting transformLinkUri or transformImageUri 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.
It lets you define your own schema of what is and isn’t allowed.
Related
— JSX in markdown
remark-gfm
— add support for GitHub flavored markdown support
react-remark
— modern hook based alternative
rehype-react
— turn HTML into React elements
Contribute
See contributing.md in remarkjs/.github for ways
to get started.
See support.md for ways to get help.
This project has a code of conduct.
By interacting with this repository, organization, or community you agree to
abide by its terms.
License