search

remarkjs / react-markdown

Markdown component for React
https://remarkjs.github.io/react-markdown/
MIT License
13.26k stars 876 forks source link
commonmark gfm markdown react remark

readme

react-markdown

Build Coverage Downloads Size Sponsors Backers Chat

React component to render markdown.

Feature highlights

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 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 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, 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 16+), install with npm:

npm install react-markdown

In Deno with esm.sh:

import Markdown from 'https://esm.sh/react-markdown@9'

In browsers with esm.sh:

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

Hi, Pluto!

```

Here is an example that shows how to use a plugin (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 ```jsx

Just a link: www.nasa.gov.

```

API

This package exports the following identifier: defaultUrlTransform. The default export is Markdown.

Markdown

Component to render markdown.

Parameters
Returns

React element (JSX.Element).

defaultUrlTransform(url)

Make a URL safe.

Parameters
Returns

Safe URL (string).

AllowElement

Filter elements (TypeScript type).

Parameters
Returns

Whether to allow element (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

Options

Configuration (TypeScript type).

Fields

UrlTransform

Transform URLs (TypeScript type).

Parameters
Returns

Transformed URL (string, optional).

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 {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 ```jsx <>

A paragraph with emphasis and strong importance.

A block quote with strikethrough and a URL:{' '} https://reactjs.org.

  • Lists
  • todo
  • done

A table:

a b
```

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 {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 ```jsx

This ~is not~ strikethrough, but this is!

```

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 {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 ```jsx <>

Here is some JavaScript code:
```

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 {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 ```jsx

The lift coefficient ( {/* … */} ) 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:

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 the additional types AllowElement, ExtraProps, Components, Options, and UrlTransform.

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 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 {createRoot} from 'react-dom/client'
import Markdown from 'react-markdown'
import rehypeRaw from 'rehype-raw'

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

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

</div>`

createRoot(document.body).render(
  <Markdown rehypePlugins={[rehypeRaw]}>{markdown}</Markdown>
)
Show equivalent JSX ```jsx

Some emphasis and strong!

```

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(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, 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 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 expression 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 of react-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. It lets you define your own schema of what is and isn’t allowed.

Related

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