npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2020 – Pkg Stats / Ryan Hefner

react-markdown

v5.0.3

Published

Render Markdown as React components

Downloads

2,820,727

Readme

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)
<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 plugins={[gfm]} children={markdown} />, document.body)
<p>
  Just a link: <a href="https://reactjs.com">https://reactjs.com</a>.
</p>

API

props

  • children (string, default: '')
    Markdown to parse
  • className (string?)
    Wrap the markdown in a div with this class name
  • allowDangerousHtml (boolean, default: false)
    This project is safe by default and escapes HTML. Use allowDangerousHtml: true to allow dangerous html instead. See security
  • skipHtml (boolean, default: false)
    Ignore HTML in Markdown
  • sourcePos (boolean, default: false)
    Pass a prop to all renderers with a serialized position (data-sourcepos="3:1-3:13")
  • rawSourcePos (boolean, default: false)
    Pass a prop to all renderers with their position (sourcePosition: {start: {line: 3, column: 1}, end:…})
  • includeNodeIndex (boolean, default: false)
    Pass index and parentChildCount in props to all renderers
  • allowedTypes (Array.<string>, default: list of all types)
    Node types to allow (can’t combine w/ disallowedTypes). All types are available at ReactMarkdown.types
  • disallowedTypes (Array.<string>, default: [])
    Node types to disallow (can’t combine w/ allowedTypes)
  • allowNode ((node, index, parent) => boolean?, optional)
    Function called to check if a node is allowed (when truthy) or not. allowedTypes / disallowedTypes is used first!
  • unwrapDisallowed (boolean, default: false)
    Extract (unwrap) the children of not allowed nodes. By default, when strong is not allowed, it and it’s content is dropped, but with unwrapDisallowed the node itself is dropped but the content used
  • linkTarget (string or (url, text, title) => string, optional)
    Target to use on links (such as _blank for <a target="_blank"…)
  • transformLinkUri ((uri) => string, default: ./uri-transformer.js, optional)
    URL to use for links. The default allows only http, https, mailto, and tel, and is available at ReactMarkdown.uriTransformer. Pass null to allow all URLs. See security
  • transformImageUri ((uri) => string, default: ./uri-transformer.js, optional)
    Same as transformLinkUri but for images
  • renderers (Object.<Component>, default: {})
    Object mapping node types to React components. Merged with the default renderers (available at ReactMarkdown.renderers). Which props are passed varies based on the node
  • plugins (Array.<Plugin>, default: [])
    List of remark plugins to use. See the next section for examples on how to pass options

Examples

Use a plugin

This example shows how to use a 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 plugins={[gfm]} children={markdown} />, document.body)
<>
  <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 plugins={[[gfm, {singleTilde: false}]]}>
    This ~is not~ strikethrough, but ~~this is~~!
  </ReactMarkdown>,
  document.body
)
<p>
  This ~is not~ strikethrough, but <del>this is</del>!
</p>

Use custom renderers (syntax highlight)

This example shows how you can overwrite the normal handling of a node by passing a renderer. 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'
import {dark} from 'react-syntax-highlighter/dist/esm/styles/prism'
import {render} from 'react-dom'

const renderers = {
  code: ({language, value}) => {
    return <SyntaxHighlighter style={dark} language={language} children={value} />
  }
}

// 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 renderers={renderers} children={markdown} />, document.body)
<>
  <p>Here is some JavaScript code:</p>
  <SyntaxHighlighter language="js" style={dark} children="console.log('It works!')" />
</>

Use a plugin and custom renderers (math)

This example shows how a syntax extension is used to support math in markdown that adds new node types (remark-math), which are then handled by renderers to use react-katex:

import React from 'react'
import ReactMarkdown from 'react-markdown'
import {InlineMath, BlockMath} from 'react-katex'
import {render} from 'react-dom'
import math from 'remark-math'
import 'katex/dist/katex.min.css' // `react-katex` does not import the CSS for you

const renderers = {
  inlineMath: ({value}) => <InlineMath math={value} />,
  math: ({value}) => <BlockMath math={value} />
}

render(
  <ReactMarkdown
    plugins={[math]}
    renderers={renderers}
    children={`The lift coefficient ($C_L$) is a dimensionless coefficient.`}
  />,
  document.body
)
<p>
  The lift coefficient (<InlineMath math="C_L" />) is a dimensionless coefficient.
</p>

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), you can react-markdown/with-html:

const React = require('react')
const ReactMarkdownWithHtml = require('react-markdown/with-html')
const render = require('react-dom').render

const markdown = `
This Markdown contains <a href="https://en.wikipedia.org/wiki/HTML">HTML</a>, and will require the <code>html-parser</code> AST plugin to be loaded, in addition to setting the <code class="prop">allowDangerousHtml</code> property to false.
`

render(<ReactMarkdownWithHtml children={markdown} allowDangerousHtml />, document.body)
<p>
  This Markdown contains <a href="https://en.wikipedia.org/wiki/HTML">HTML</a>, and will require
  the <code>html-parser</code> AST plugin to be loaded, in addition to setting the{' '}
  <code className="prop">allowDangerousHtml</code> property to false.
</p>

If you want to specify options for the HTML parsing step, you can instead import the extension directly:

const ReactMarkdown = require('react-markdown')
const htmlParser = require('react-markdown/plugins/html-parser')

// For more info on the processing instructions, see
// <https://github.com/aknuds1/html-to-react#with-custom-processing-instructions>
const parseHtml = htmlParser({
  isValidNode: (node) => node.type !== 'script',
  processingInstructions: [
    /* ... */
  ]
})

<ReactMarkdown astPlugins={[parseHtml]} allowDangerousHtml children={markdown} />

Appendix B: Node types

The node types available by default are:

  • root — Whole document
  • text — Text (foo)
  • break — Hard break (<br>)
  • paragraph — Paragraph (<p>)
  • emphasis — Emphasis (<em>)
  • strong — Strong (<strong>)
  • thematicBreak — Horizontal rule (<hr>)
  • blockquote — Block quote (<blockquote>)
  • link — Link (<a>)
  • image — Image (<img>)
  • linkReference — Link through a reference (<a>)
  • imageReference — Image through a reference (<img>)
  • list — List (<ul> or <ol>)
  • listItem — List item (<li>)
  • definition — Definition for a reference (not rendered)
  • heading — Heading (<h1> through <h6>)
  • inlineCode — Inline code (<code>)
  • code — Block of code (<pre><code>)
  • html — HTML node (Best-effort rendering)
  • virtualHtml — If allowDangerousHtml is not on and skipHtml is off, a naive HTML parser is used to support basic HTML
  • parsedHtml — If allowDangerousHtml is on, skipHtml is off, and html-parser is used, more advanced HTML is supported

With remark-gfm, the following are also available:

  • delete — Delete text (<del>)
  • table — Table (<table>)
  • tableHead — Table head (<thead>)
  • tableBody — Table body (<tbody>)
  • tableRow — Table row (<tr>)
  • tableCell — Table cell (<td> or <th>)

Security

Use of react-markdown is secure by default. Overwriting transformLinkUri or transformImageUri to something insecure or turning allowDangerousHtml on, will open you up to XSS vectors. Furthermore, the plugins you use and renderers you write may be insecure.

Related

  • MDX — JSX in markdown
  • remark-gfm — Plugin for GitHub flavored markdown support

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