@cquiroz/react-markdown
v6.0.0
Published
Render Markdown as React components
Downloads
3
Maintainers
Readme
react-markdown
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 require
s, 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)
<p>
Just a link: <a href="https://reactjs.com">https://reactjs.com</a>.
</p>
API
props
children
(string
, default:''
)
Markdown to parseclassName
(string?
)
Wrap the markdown in adiv
with this class nameskipHtml
(boolean
, default:false
)
Ignore HTML in Markdown completelysourcePos
(boolean
, default:false
)
Pass a prop to all components with a serialized position (der>nfdata-sourceposder>nth="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 theindex
(number of elements before it) andsiblingCount
(number of elements in parent) as props to all componentsallowedElements
(Array.<string>
, default:undefined
)
Tag names to allow (can’t combine w/disallowedElements
). By default all elements are alloweddisallowedElements
(Array.<string>
, default:undefined
)
Tag names to disallow (can’t combine w/allowedElements
). By default no elements are disallowedallowElement
((element, index, parent) => boolean?
, optional)
Function called to check if an element is allowed (when truthy) or not.allowedElements
/disallowedElements
is used first!unwrapDisallowed
(boolean
, default:false
)
Extract (unwrap) the children of not allowed elements. By default, whenstrong
is not allowed, it and it’s children is dropped, but withunwrapDisallowed
the element itself is dropped but the children usedlinkTarget
(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:./uri-transformer.js
, optional)
URL to use for links. The default allows onlyhttp
,https
,mailto
, andtel
, and is available atReactMarkdown.uriTransformer
. Passnull
to allow all URLs. See securitytransformImageUri
((src, alt, title) => string
, default:./uri-transformer.js
, optional)
Same astransformLinkUri
but for imagescomponents
(Object.<string, Component>
, default:{}
)
Object mapping tag names to React componentsremarkPlugins
(Array.<Plugin>
, default:[]
)
List of remark plugins to use. See the next section for examples on how to pass optionsrehypePlugins
(Array.<Plugin>
, default:[]
)
List of rehype 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 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)
<>
<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
)
<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'
import {dark} from 'react-syntax-highlighter/dist/esm/styles/prism'
import {render} from 'react-dom'
const components = {
code({node, className, ...props}) {
const match = /language-(\w+)/.exec(className || '')
return match
? <SyntaxHighlighter language={match[1]} PreTag="div" style={dark} {...props} />
: <code className={className} {...props} />
}
}
// 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)
<>
<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
)
<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>
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)
<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.
code
inline
(boolean?
) — set totrue
for inline codeclassName
(string?
) — set tolanguage-js
or so when using```js
h1
,h2
,h3
,h4
,h5
,h6
level
(number
beween 1 and 6) — heading rank
input
(when usingremark-gfm
)checked
(boolean
) — whether the item is checkeddisabled
(true
)type
('checkbox'
)
li
index
(number
) — number of preceding items (so first gets0
, etc.)ordered
(boolean
) — whether the parent is anol
or notchecked
(boolean?
) —null
normally,boolean
when usingremark-gfm
’s tasklistsclassName
(string?
) — set totask-list-item
when usingremark-gfm
and the item1 is a tasklist
ol
,ul
depth
(number
) — number of ancestral lists (so first gets0
, etc.)ordered
(boolean
) — whether it’s anol
or notclassName
(string?
) — set tocontains-task-list
when usingremark-gfm
and the list contains one or more tasklists
td
,th
(when usingremark-gfm
)style
(Object?
) — something like{textAlign: 'left'}
depending on how the cell is alignedisHeader
(boolean
) — whether it’s ath
or not
tr
(when usingremark-gfm
)isHeader
(boolean
) — whether it’s in thethead
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
) — seesourcePos
optionsourcePosition
(Object
) — seerawSourcePos
optionindex
andsiblingCount
(number
) — seeincludeElementIndex
optiontarget
ona
(string
) — seelinkTarget
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
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.
Related
MDX
— JSX in markdownremark-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.