react-remark

The react-remark architecture follows a unified pipeline that transforms raw markdown into React elements through several stages:

1. Markdown $\rightarrow$ remark: Parses markdown into an mdast (Markdown Abstract Syntax Tree).
2. remark plugins: Transform the mdast.
3. remark-rehype: Converts mdast into hast (Hypertext Abstract Syntax Tree).
4. rehype plugins: Transform the hast.
5. rehype-react: Converts hast into React elements.

Install react-remark using npm or yarn to render Markdown into React elements using the remark ecosystem.

npm install --save react-remark
# or
yarn add react-remark

The useRemark hook provides a stateful way to manage markdown content and its rendered React output. It returns an array containing the rendered reactContent and a setMarkdownSource function to update the input string.

Use this pattern for interactive markdown editors or when markdown content is fetched asynchronously.

import React, { useEffect } from 'react';
import { useRemark } from 'react-remark';

const ExampleComponent = () => {
  const [reactContent, setMarkdownSource] = useRemark();

  useEffect(() => {
    setMarkdownSource('# markdown header');
  }, []);

  return reactContent;
};

The useRemarkSync hook is designed for synchronous rendering, making it suitable for Server Side Rendering (SSR).

Warning: Some remark plugins are asynchronous. If you use asynchronous plugins, they will cause an error when used with useRemarkSync.

import React from 'react';
import { useRemarkSync } from 'react-remark';

const ExampleComponent = () => {
  const reactContent = useRemarkSync('# markdown header');

  return reactContent;
};

The <Remark> component is a declarative way to render markdown. You can pass the markdown string as children to the component.

For dynamic content, manage the markdown string in your own React state and pass it as children to <Remark>.

import React, { useState } from 'react';
import { Remark } from 'react-remark';

const ExampleComponent = () => {
  const [markdownSource, setMarkdownSource] = useState('');

  return (
    <>
      <input
        type="text"
        onChange={({ currentTarget }) => setMarkdownSource(currentTarget.value)}
      />
      <Remark>{markdownSource}</Remark>
    </>
  );
};

The Remark component is a declarative wrapper around the useRemark hook. You can pass markdown text as children, and the component will automatically handle the asynchronous processing and rendering lifecycle.

Props:

• children: The markdown string to be rendered.
• ...useRemarkOptions: Any options compatible with UseRemarkOptions (see below).

import { Remark } from 'react-remark';

const App = () => (
  <Remark 
    remarkPlugins={[]} 
    rehypePlugins={[]} 
  >
    # This is markdown
  </Remark>
);

The useRemark hook provides an asynchronous way to transform markdown strings into React elements. It returns a tuple containing the current ReactElement (or null while loading) and a setter function to update the markdown source. This is ideal for handling large markdown files or when you want to avoid blocking the main thread during processing.

Returns: [reactContent, setMarkdownSource]

• reactContent: The rendered ReactElement or null.
• setMarkdownSource: A function that accepts a string and triggers the asynchronous processing pipeline.

import { useRemark } from 'react-remark';

const MyComponent = () => {
  const [content, setMarkdown] = useRemark({
    remarkPlugins: [/* your plugins */],
    onError: (err) => console.error(err),
  });

  useEffect(() => {
    setMarkdown('# Hello World');
  }, [setMarkdown]);

  return <div>{content}</div>;
};

The useRemarkSync hook performs the markdown-to-React transformation synchronously. It is useful for small markdown strings where immediate rendering is required and you want to avoid the complexity of managing loading states or useEffect calls.

Warning: Because this uses .processSync(), it may block the main thread if the markdown source is very large or the plugin pipeline is heavy.

import { useRemarkSync } from 'react-remark';

const MyComponent = ({ markdownString }: { markdownString: string }) => {
  const content = useRemarkSync(markdownString, {
    remarkPlugins: [],
    rehypePlugins: [],
  });

  return <div>{content}</div>;
};