Guide · Open source

How to use react-markdown: render Markdown safely in React

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

react-markdown is a React component that takes a string of Markdown and turns it into React elements on the page. This guide shows you how to install it, render your first Markdown string, add a plugin for GitHub Flavored Markdown and replace rendered tags with your own components. By the end you will know the core props and when this package is the right choice.

react-markdownremarkjs/react-markdown · ★ 15.9k · MIT Install options & downloads

Quick start

1Check prerequisites. Confirm you have Node.js 16 or newer and a React project.
2Install the package. Run npm install react-markdown in your project folder.
3Import the component. Import the default export, Markdown, from react-markdown.
4Pass Markdown as children. Wrap your Markdown string in the Markdown component, for example <Markdown>{markdown}</Markdown>.
5Add plugins if needed. For tables, task lists and strikethrough, install remark-gfm and pass it in remarkPlugins.
6Customise tags. Use the components prop to replace tags such as h2 with your own React components.

What react-markdown is and when to use it

react-markdown avoids dangerouslySetInnerHTML, so it is designed to be safe by default against XSS. It builds a virtual DOM from a syntax tree, so React only replaces what changed.

It suits React developers who need to display Markdown such as comments, docs or posts. If you want JavaScript or JSX inside Markdown files, the README points to MDX instead.

Good fit: displaying comments, docs or posts in a React app
Good fit: swapping tags like h2 for your own React components
Not a fit: embedding JSX inside Markdown files (use MDX)
Not a fit: projects that do not use React

Install react-markdown with npm

The package is ESM only. In Node.js (version 16+), install it with npm. Prerequisites are Node.js 16+ and React.

npm install react-markdown

Render your first Markdown string

Import the default export, which is the Markdown component, and pass your Markdown text as its children. The README's example renders a heading with emphasis, so '# Hi, *Pluto*!' becomes an h1 containing an em element.

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

Add GitHub Flavored Markdown with remark-gfm

react-markdown is 100% CommonMark, but GitHub Flavored Markdown needs a plugin. The README uses remark-gfm, which adds footnotes, strikethrough, tables, tasklists and URLs written without angle brackets. Pass plugins as an array to the remarkPlugins prop.

Install the plugin with npm install remark-gfm
Import remarkGfm and add it to remarkPlugins

import Markdown from 'react-markdown'
import remarkGfm from 'remark-gfm'

<Markdown remarkPlugins={[remarkGfm]}>{markdown}</Markdown>

Replace rendered tags with custom components

The components prop maps tag names to React components. The README's example is replacing h2 for '## hi'. Each component also receives an optional node prop with the original element.

Use allowedElements or disallowedElements to control which tags render. The README notes that allowedElements and disallowedElements cannot be combined, and that skipHtml ignores HTML in Markdown completely.

components: map tag names such as h2 to your own components
skipHtml: defaults to false; set to true to ignore HTML
unwrapDisallowed: defaults to false; keeps children of disallowed elements

Choose between Markdown, MarkdownAsync and MarkdownHooks

Markdown is synchronous. If you use async plugins, the README recommends MarkdownAsync (promises, supported on the server) or MarkdownHooks (uses useEffect and useState, runs on the client, and accepts a fallback prop while processing).

What people use it for

Rendering user comments in a React app without writing HTML parsing code
Displaying documentation or blog posts written in Markdown
Replacing h2 or other tags with styled React components
Adding GFM tables and task lists to Markdown content with remark-gfm

Frequently asked questions

How do I install react-markdown?

Run npm install react-markdown in a Node.js project (version 16 or newer). The package is ESM only. The README also shows esm.sh imports for Deno and browsers.

Is react-markdown free to use?

The package is licensed under MIT, as listed in the project's details. Check the repository's license file for the full terms.

Does react-markdown support GitHub Flavored Markdown tables?

Not by default. The README says it is 100% CommonMark and 100% GFM with a plugin. Add remark-gfm and pass it in the remarkPlugins prop to get tables, tasklists, strikethrough and footnotes.

Is react-markdown safe against XSS?

The README says it is safe by default because it does not use dangerouslySetInnerHTML. It also filters URLs with defaultUrlTransform, which allows http, https, irc, ircs, mailto, xmpp and relative URLs.

What is the difference between react-markdown and MDX?

react-markdown renders a string of Markdown. MDX lets you embed JavaScript and JSX inside Markdown files, which react-markdown does not do. The README points to MDX for that use case.

What are the alternatives to react-markdown?

The README names react-remark and rehype-react as options for developers who know unified well and want a hooks-based approach. MDX is the choice when you need JSX inside Markdown.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use react-markdown if you are a React developer who needs to display Markdown safely and may want to swap tags for your own components. Pick MDX if you need JSX inside your Markdown files, or react-remark or rehype-react if you already know unified well and prefer a hooks-based approach.

Install options & downloads