• Stars
    star
    12,885
  • Rank 2,467 (Top 0.05 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created over 9 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Markdown component for React

react-markdown

Build Coverage Downloads Size Sponsors Backers Chat

React component to render markdown.

Feature highlights

  • safe by default (no dangerouslySetInnerHTML or XSS attacks)
  • components (pass your own component to use instead of <h2> for ## hi)
  • plugins (many plugins you can pick and choose from)
  • compliant (100% to CommonMark, 100% to GFM with a plugin)

Contents

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 to React elements and pass components that will be used instead of normal HTML elements.

When should I use this?

There are other ways to use 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 compliant and has plugins to support other syntax extensions (such as GFM).

These features are 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 or rehype-react manually. If you instead want to use JavaScript and JSX inside markdown files, use MDX.

Install

This package is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:

npm install react-markdown

In Deno with esm.sh:

import ReactMarkdown from 'https://esm.sh/react-markdown@7'

In browsers with esm.sh:

<script type="module">
  import ReactMarkdown from 'https://esm.sh/react-markdown@7?bundle'
</script>

Use

A basic hello world:

import React from 'react'
import ReactMarkdown from 'react-markdown'
import ReactDom from 'react-dom'

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

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

import React from 'react'
import ReactDom from 'react-dom'
import ReactMarkdown from 'react-markdown'
import remarkGfm from 'remark-gfm'

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

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

API

This package exports the following identifier: uriTransformer. The default export is ReactMarkdown.

props

  • children (string, default: '')
    markdown to parse
  • components (Record<string, Component>, default: {})
    object mapping tag names to React components
  • remarkPlugins (Array<Plugin>, default: [])
    list of remark plugins to use
  • rehypePlugins (Array<Plugin>, default: [])
    list of rehype plugins to use
  • remarkRehypeOptions (Object?, default: undefined)
    options to pass through to remark-rehype
  • className (string?)
    wrap the markdown in a div with this class name
  • skipHtml (boolean, default: false)
    ignore HTML in markdown completely
  • sourcePos (boolean, default: false)
    pass a prop to all components with a serialized position (data-sourcepos="3:1-3:13")
  • rawSourcePos (boolean, default: false)
    pass a prop to all components with their position (sourcePosition: {start: {line: 3, column: 1}, end:โ€ฆ})
  • includeElementIndex (boolean, default: false)
    pass the index (number of elements before it) and siblingCount (number of elements in parent) as props to all components
  • allowedElements (Array<string>, default: undefined)
    tag names to allow (canโ€™t combine w/ disallowedElements), all tag names are allowed by default
  • disallowedElements (Array<string>, default: undefined)
    tag names to disallow (canโ€™t combine w/ allowedElements), all tag names are allowed by default
  • allowElement ((element, index, parent) => boolean?, optional)
    function called to check if an element is allowed (when truthy) or not, allowedElements or disallowedElements is used first!
  • unwrapDisallowed (boolean, default: false)
    extract (unwrap) the children of not allowed elements, by default, when strong is disallowed, it and itโ€™s children are dropped, but with unwrapDisallowed the element itself is replaced by its children
  • linkTarget (string or (href, children, title) => string, optional)
    target to use on links (such as _blank for <a target="_blank"โ€ฆ)
  • transformLinkUri ((href, children, title) => string, default: uriTransformer, optional)
    change URLs on links, pass null to allow all URLs, see security
  • transformImageUri ((src, alt, title) => string, default: uriTransformer, optional)
    change URLs on images, pass null to allow all URLs, see security

uriTransformer

Our default URL transform, which you can overwrite (see props above). Itโ€™s given a URL and cleans it, by allowing only http:, https:, mailto:, and tel: URLs, absolute paths (/example.png), and hashes (#some-place).

See the source code here.

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 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
<>
  <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 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
<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 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>
  <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 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
<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>

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:

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 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, alt and title, etc. There are some extra props passed.

  • code
    • inline (boolean?) โ€” set to true for inline code
    • className (string?) โ€” set to language-js or so when using ```js
  • h1, h2, h3, h4, h5, h6
    • level (number between 1 and 6) โ€” heading rank
  • input (when using remark-gfm)
    • checked (boolean) โ€” whether the item is checked
    • disabled (true)
    • type ('checkbox')
  • li
    • index (number) โ€” number of preceding items (so first gets 0, etc.)
    • ordered (boolean) โ€” whether the parent is an ol or not
    • checked (boolean?) โ€” null normally, boolean when using remark-gfmโ€™s tasklists
    • className (string?) โ€” set to task-list-item when using remark-gfm and the item1 is a tasklist
  • ol, ul
    • depth (number) โ€” number of ancestral lists (so first gets 0, etc.)
    • ordered (boolean) โ€” whether itโ€™s an ol or not
    • className (string?) โ€” set to contains-task-list when using remark-gfm and the list contains one or more tasklists
  • td, th (when using remark-gfm)
    • 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

  • MDX โ€” 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

MIT ยฉ Espen Hovlandsdal

More Repositories

1

remark

markdown processor powered by plugins part of the @unifiedjs collective
JavaScript
7,513
star
2

remark-lint

plugins to check (lint) markdown code style
JavaScript
936
star
3

remark-gfm

remark plugin to support GFM (autolink literals, footnotes, strikethrough, tables, tasklists)
JavaScript
701
star
4

remark-react

Legacy plugin to transform to React โ€” please use `remark-rehype` and `rehype-react` instead
JavaScript
524
star
5

remark-toc

plugin to generate a table of contents (TOC)
JavaScript
408
star
6

awesome-remark

Curated list of awesome remark resources
374
star
7

remark-math

remark and rehype plugins to support math
JavaScript
364
star
8

remark-html

plugin to add support for serializing HTML
JavaScript
312
star
9

remark-rehype

plugin that turns markdown into HTML to support rehype
JavaScript
258
star
10

remark-frontmatter

remark plugin to support frontmatter (YAML, TOML, and more)
JavaScript
253
star
11

remark-directive

remark plugin to support directives
JavaScript
247
star
12

react-remark

React component and hook to use remark to render markdown
TypeScript
201
star
13

remark-github

remark plugin to link references to commits, issues, pull-requests, and users, like on GitHub
JavaScript
173
star
14

strip-markdown

plugin remove Markdown formatting
JavaScript
134
star
15

remark-breaks

plugin to add break support, without needing spaces
JavaScript
116
star
16

remark-validate-links

plugin to check that Markdown links and images reference existing files and headings
JavaScript
109
star
17

remark-man

plugin to compile markdown to man pages
JavaScript
93
star
18

remark-slug

Legacy plugin to add `id`s to headings โ€” please use `rehype-slug`
JavaScript
89
star
19

remark-lint-no-dead-urls

Ensure that external links in your Markdown are alive
JavaScript
77
star
20

remark-unwrap-images

plugin to remove the wrapping paragraph for images
JavaScript
75
star
21

remark-highlight.js

Legacy plugin to highlight code blocks with highlight.js โ€” please use `rehype-highlight` instead
JavaScript
70
star
22

remark-autolink-headings

Legacy remark plugin to automatically add links to headings โ€” please use `rehype-autolink-headings` instead
JavaScript
64
star
23

remark-external-links

Legacy plugin to automatically add target and rel attributes to external links โ€” please use `rehype-external-links` instead
JavaScript
56
star
24

vscode-remark

Lint and format markdown code with remark
JavaScript
54
star
25

remark-vdom

Legacy plugin to compile Markdown to Virtual DOM โ€” please use `remark-rehype` and then something like `rehype-react`
JavaScript
45
star
26

remark-usage

plugin to add a usage example to your readme
JavaScript
42
star
27

remark-gemoji

plugin to turn gemoji shortcodes into emoji ๐Ÿ‘
JavaScript
41
star
28

remark-footnotes

Legacy plugin to add support for pandoc footnotes โ€” please use `remark-gfm` instead
JavaScript
40
star
29

remark-images

plugin to add a simpler image syntax
JavaScript
35
star
30

remark-textr

plugin to make your typography better with Textr
JavaScript
35
star
31

remark-language-server

A language server to lint and format markdown files with remark
JavaScript
33
star
32

remark-embed-images

plugin to embed local images as data URIs
HTML
33
star
33

remark-jsx

A simple way to use React inside Markdown.
JavaScript
28
star
34

remark-reference-links

plugin to change links and images to references with separate definitions
JavaScript
25
star
35

remark-retext

plugin to transform from remark (Markdown) to retext (natural language)
JavaScript
25
star
36

remark-inline-links

plugin to change references and definitions into normal links and images
JavaScript
23
star
37

remark-contributors

plugin to generate a list of contributors
JavaScript
22
star
38

remark-license

plugin to generate a license section
JavaScript
19
star
39

remark-defsplit

plugin to change links and images to references with separate definitions
JavaScript
19
star
40

remark-bookmarks

plugin to manage links
JavaScript
15
star
41

remark-comment-config

plugin to configure remark with comments
JavaScript
14
star
42

remark-git-contributors

plugin to generate a list of Git contributors
JavaScript
12
star
43

remark-normalize-headings

plugin to make sure there is a single top level heading in a document by adjusting heading ranks accordingly
JavaScript
11
star
44

remark-squeeze-paragraphs

plugin to remove empty (or white-space only) paragraphs
JavaScript
10
star
45

remark-strip-badges

plugin to strip badges (such as shields.io)
JavaScript
9
star
46

gulp-remark

Legacy Gulp plugin for remark โ€” please use npm scripts and the like
JavaScript
9
star
47

remark-yaml-config

plugin to configure remark with YAML frontmatter
JavaScript
8
star
48

remark-message-control

plugin to enable, disable, and ignore messages
JavaScript
8
star
49

.github

Community health files for remark
TypeScript
7
star
50

remark-unlink

plugin to remove all links, images, references, and definitions
JavaScript
6
star
51

remark-heading-gap

plugin to adjust the gap between headings in markdown
JavaScript
6
star
52

ideas

Share ideas for new utilities and tools built with @remarkjs
5
star
53

remark-word-wrap

Please use something like https://github.com/prettier/prettier instead
JavaScript
4
star
54

grunt-remark

Grunt task for remark
4
star
55

remark-midas

plugin to highlight CSS code blocks with midas
3
star
56

remark-comment-blocks

Use something like https://github.com/3rd-Eden/commenting instead
JavaScript
2
star
57

governance

How @remarkjs and the projects under it are governed
2
star