unified

Project: remarkjs/react-markdown

Package: react-markdown@6.0.2

  1. Dependencies: 13·Dependents: 762
  2. Render Markdown as React components
  1. remark 195
  2. unified 167
  3. markdown 135
  4. ast 31
  5. gfm 16
  6. react 16
  7. commonmark 5

react-markdown

Build Coverage Downloads Size Sponsors Backers Chat

Markdown component for React using remark.

Learn markdown here and check out the demo here.

Install

npm:

npm install react-markdown

Why this one?

There are other ways for markdown in React out there so why use this one? The two main reasons are that they often rely on dangerouslySetInnerHTML or have bugs with how they handle markdown. react-markdown uses a syntax tree to build the virtual dom which allows for updating only the changing DOM instead of completely overwriting. react-markdown is 100% CommonMark (optionally GFM) compliant and has extensions to support custom syntax.

Use

A basic hello world:

import React from 'react'
import ReactMarkdown from 'react-markdown'
import {render} from 'react-dom'

render(<ReactMarkdown># Hello, *world*!</ReactMarkdown>, document.body)
Show equivalent JSX
<h1>
  Hello, <em>world</em>!
</h1>

Here is an example using requires, passing the markdown as a string, and how to use a plugin (remark-gfm, which adds support for strikethrough, tables, tasklists and URLs directly):

const React = require('react')
const ReactMarkdown = require('react-markdown')
const render = require('react-dom').render
const gfm = require('remark-gfm')

const markdown = `Just a link: https://reactjs.com.`

render(<ReactMarkdown remarkPlugins={[gfm]} children={markdown} />, document.body)
Show equivalent JSX
<p>
  Just a link: <a href="https://reactjs.com">https://reactjs.com</a>.
</p>

API

props

Examples

Use a plugin

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

import React from 'react'
import ReactMarkdown from 'react-markdown'
import {render} from 'react-dom'
import gfm 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 |
| - | - |
`

render(<ReactMarkdown remarkPlugins={[gfm]} children={markdown} />, document.body)
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>
    <li>Lists</li>
    <li>
      <input checked={false} readOnly={true} type="checkbox" /> todo
    </li>
    <li>
      <input checked={true} readOnly={true} type="checkbox" /> done
    </li>
  </ul>
  <p>A table:</p>
  <table>
    <thead>
      <tr>
        <td>a</td>
        <td>b</td>
      </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 has an option to allow only double tildes for strikethrough:

import React from 'react'
import ReactMarkdown from 'react-markdown'
import {render} from 'react-dom'
import gfm from 'remark-gfm'

render(
  <ReactMarkdown remarkPlugins={[[gfm, {singleTilde: false}]]}>
    This ~is not~ strikethrough, but ~~this is~~!
  </ReactMarkdown>,
  document.body
)
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 amazing react-syntax-highlighter by @conorhastings:

import React from 'react'
import ReactMarkdown from 'react-markdown'
import {Prism as SyntaxHighlighter} from 'react-syntax-highlighter'
/* Use `…/dist/cjs/…` if you’re not in ESM! */
import {dark} from 'react-syntax-highlighter/dist/esm/styles/prism'
import {render} from 'react-dom'

const components = {
  code({node, inline, className, children, ...props}) {
    const match = /language-(\w+)/.exec(className || '')
    return !inline && match ? (
      <SyntaxHighlighter style={dark} language={match[1]} PreTag="div" children={String(children).replace(/\n$/, '')} {...props} />
    ) : (
      <code className={className} {...props}>
        {children}
      </code>
    )
  }
}

// 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!')
~~~
`

render(<ReactMarkdown components={components} children={markdown} />, document.body)
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 (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 {render} 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

render(
  <ReactMarkdown
    remarkPlugins={[remarkMath]}
    rehypePlugins={[rehypeKatex]}
    children={`The lift coefficient ($C_L$) is a dimensionless coefficient.`}
  />,
  document.body
)
Show equivalent JSX
<p>
  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.
</p>

Architecture

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

relevant links: markdown, remark, mdast, remark plugins, remark-rehype, hast, rehype plugins, components

To understand what this project does, it’s very 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:

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 ReactMarkdown from 'react-markdown'
import rehypeRaw from 'rehype-raw'
import {render} from 'react-dom'

const input = `<div class="note">

Some *emphasis* and <strong>strong</strong>!

</div>`

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:

<Markdown
  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, code, em, h1, h2, h3, h4, h5, h6, hr, img, li, ol, p, pre, strong, and ul. 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 (and title), etc. There are some extra props passed.

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:

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 and rehypePlugins you use and components you write may be insecure.

To make sure the content is completely safe, even after what plugins do, use rehype-sanitize. That plugin lets you define your own schema of what is and isn’t allowed.

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

MIT © Espen Hovlandsdal