How to render and edit Markdown in React with react-markdown

With React frameworks like Next.js leading the charge with highly performant rendering strategies such as static site generation (SSG), React has positioned itself as an attractive technology to implement content-driven sites like blogs and marketing pages.

Since Markdown is a popular content format, developers need to be able to work with it in React.

This post will show you how to integrate and render Markdown in React using the react-markdown library, enabling you to build fast, content-driven pages. 

How to use react-markdown to render Markdown

The following tutorial will show you how to render Markdown in your React apps with react-markdown, which is just a lightweight package that parses Markdown and returns safe, styled React elements. These elements then get rendered as HTML by the browser. 

You'll need a basic React app to get started. If you need help bootstrapping a new React project, then our React quickstart guide can help you get up and running. Alternatively, you can use Vite to start a new project:

npm create vite@latest react-markdown-example -- --template react

First you need to install the react-markdown package:

npm install react-markdown

Once the package has finished installing, you can import the ReactMarkdown component and use it inside your own React components as shown below:

The above code demonstrates some basic Markdown syntax (headers, links, images), which is stored in a variable. To render the Markdown as HTML, you only need to wrap the string with the ReactMarkdown component and run your app. You'll see the following output in your browser:

By default, your Markdown will be converted into standard HTML tags (for example, <h1>, <p>, and <a>), but you can add your own customization for how these elements look (or behave) using the components prop in react-markdown. For example, you might want to style these elements to match your own branding or ensure that all links open in a new tab. The code below shows how to use the components prop to do this.

In the above code, the components prop is an object that is mapping Markdown elements — represented by their equivalent HTML tag names (for example, h1 and a) — to custom React components. This is done using inline functional components.

Each functional component receives values like node and props, which allow you to change behavior and styling. For instance, we changed the color of the elements to blue and changed all links to open in a new tab by customizing the a tag and adding target="_blank" to it.

In summary, react-markdown parses input Markdown and turns it into native React elements, and if you need full control over how each tag renders, you can use the components prop.

You can access live examples of this code at this sandbox link.

How to create a React Markdown editor for end users

The react-markdown package deals with everything to do with rendering Markdown, but if you need to provide an interface for users to edit Markdown (such as blog editors, internal tools, etc.), you will need to install a package called react-md-editor:

npm i @uiw/react-md-editor

The example below will render a basic Markdown editor in your React app:

When you enter your Markdown text into the react markdown editor, the code above uses the onChange event handler to update local state in the parent component, keeping the editor and the live preview in sync. Any text entered into the editor on the left can be seen as a preview, updated in real time on the right. The editor also provides a number of different controls to help your users when writing Markdown, such as buttons for bold text, italics, and links.

You can access live examples of this code at this sandbox link.

Security with react-md-editor

You may be using react-md-editor as an editing tool for your users creating content or as a back office (in a CMS or admin tool). If you're planning to save that Markdown and render it later elsewhere, it's important to either avoid rendering raw HTML or to sanitize your content before rendering to prevent XSS attacks. This is especially true if you allow HTML in the Markdown or you are rendering the content in a public-facing app. We will cover tips for sanitizing your content next.

React Markdown best practices and tips

Security

It's generally a bad idea to render raw HTML in Markdown, so it's disabled by default in react-markdown. This means if you try to use HTML tags like <script> or <iframe>, then they won't be rendered as HTML; they will just be treated as text, which helps reduce threats like cross-site scripting (XSS) attacks. 

However, sometimes you may want to add more dynamic elements to your Markdown, such as an online video, a map, or a web form. Markdown is intended for content, not complex layouts, so this is not recommended; however, if you need to, you can use extra plugins like rehype-raw to allow the rendering of raw HTML in Markdown — but then you will need to sanitize your content with a plugin called rehype-sanitize. This acts as a whitelist-based filter that allows safe tags by default (<h1>, <p>, etc. ) and strips out dangerous tags like <script> and <iframe>:

In the above example, the script tag will be removed. Since rehype-sanitize will remove dangerous elements like iframes too, it’s worth noting that if you wanted to work with YouTube videos, for instance, you could set up a custom configuration to allow all iframes from youtube.com.

Accessibility

Accessibility best practices aren’t built into Markdown. Writers need to be aware of some things like adding alt text to images or descriptive text to links, but writers cannot add Accessible Rich Internet Applications (ARIA) attributes. If your Markdown includes modals, tabs, or buttons, these UI elements won't have the right ARIA attributes right away. Developers can fix this by using custom components (via the components prop) to inject the correct ARIA attributes where needed. Markdown does support tables, but they aren't always responsive, and you'll have to add accessible labels and keyboard support with custom components.

The above code demonstrates how you can use a custom component to add an ARIA attribute to an element.

Performance

Rendering with react-markdown is usually quite fast, but excessive plugin usage or big Markdown files can introduce some rendering delays. Parsing overly large files using react-markdown will cause significant latency, but this is something that the community is actively working on improving. In the meantime, you'll have improved performance if you keep your Markdown files reasonably sized, splitting your content into chunks if the rendering becomes too slow.

Storage and format

Always store Markdown as plain text strings. Markdown is designed to be lightweight and flexible. If it’s stored as a string, it's easily editable, and you can parse or transform it dynamically. Plus, by avoiding storing it as HTML, you avoid some security risks. Markdown should be used purely for content — any logic or data should be kept in secure backend environments. Popular CMSes like Contentful allow you to store Markdown content as raw text fields, making it portable and flexible.

React Markdown plugins and associated packages

The creators of react-markdown, Remark, have built a number of packages to help you achieve different purposes when rendering Markdown:

• remark-gfm allows you to render GitHub-flavored Markdown (GFM), an extended version of Markdown popularized by GitHub. It adds support for tables, task lists, and strikethrough, among other features.

• mdx allows you to write JSX in your Markdown documents. You can add interactive elements like charts or alerts and embed them with your content.

• rehype-highlight allows syntax highlighting in any code blocks used within your Markdown.

• rehype-raw allows you to add raw HTML to your Markdown, as mentioned earlier, you can embed HTML in your Markdown, but it's recommended to use together with rehype-sanitize to sanitize and prevent security risks.

Markdown is a useful tool for rendering content efficiently, but rendering it safely with React requires some attention to security, performance, and accessibility. Stick to well-supported plugins and sanitize if you’re using raw HTML.

Use Contentful to edit and serve your Markdown

Although react-md-editor is a very useful tool, if you’d like to save time and not have to build, maintain, and secure a Markdown editor for your back office, Contentful can provide you with a CMS and intuitive interface. All content can be served over REST or GraphQL APIs, from a global, high-speed CDN. All you need to do is enter your Markdown content and connect it with react-markdown in your frontend app.

Let's step through how easy this is to set up. Head over to Contentful to log in or create a free account. Once you have created a space, click the “Content model” button in the top bar. Create a new content type called “Article” by clicking “Create content type” on the right:

Now add a field of long text and give it a field name of “articleContent”.

Click “Add and configure” and then scroll down to “Appearance” on the next page and select “Markdown”.

Click “Confirm” and then save. Head over to the “Content” tab and select to add some new content in the top right, select “Article”. Now in the editor, you will be able to add some Markdown and preview it before publishing. This article on our Markdown editor can help with this. Once finished, change the status to “Published” on the right:

Once published, this content will be available for you to request over Contentful's Content Delivery API. Contentful provides a few SDKs for popular languages and frameworks that help you do this. The following example will use Contentful's JavaScript SDK, which you can install with the following command:

npm install contentful

Now you can connect to Contentful with the following code:

The VITE_CF_SPACE_ID is the Contentful space ID, and the VITE_CF_CMA_TOKEN is the Contentful Content Management API token, both of which are available from “Settings” in your Contentful dashboard.

Now that your app is connected to Contentful, you can query its API:

This will display the Markdown in the browser like so:

Curating, storing, and delivering rich text content for apps and websites

React Markdown allows you to render Markdown in your React apps, but if you want a more structured layout (embedding assets, headings, tables, etc.), Contentful also offers a “Rich Text” field.

This enables you to store content as a structured JSON document (not just plain Markdown) and is useful for custom rendering, embedding media, or designing content to be used across different channels (web, mobile, email). You can migrate your Markdown to Rich Text with our rich-text-from-markdown package, then render Rich Text in React using the rich text package.

Using Contentful makes your content omnichannel, reduces infrastructure, and gives you full control over how your content is displayed across a variety of platforms.

Start building

Sign up for a free Contentful account

Use your favorite tech stack, language, and framework of your choice.

Subscribe for updates

Build better digital experiences with Contentful updates direct to your inbox.