react-remarkify

A lightweight React.js utility to transform Markdown into React.js components seamlessly.

Features

• Effortlessly converts Markdown into React.js components.
• Simple and user-friendly API.
• Fully customizable.
• Supports plugins for enhanced functionality.
• Accepts flexible content via ReactNode, including Markdown strings or JSX.

Installation

Install react-remarkify using your preferred package manager:

# Using npm:
npm install react-remarkify --save

# Using Yarn:
yarn add react-remarkify

# Using pnpm:
pnpm add react-remarkify

# Using Bun:
bun add react-remarkify

Usage

react-remarkify provides two primary methods to incorporate Markdown into your React.js applications: the useRemark hook and the <Remark> component.

useRemark Hook

Use the useRemark hook to transform Markdown content into React.js components dynamically:

import React from "react";
import { useRemark } from "react-remarkify";

export default function App() {
  const heading = "# Welcome to the App";
  const description = "This is a **React-powered** Markdown block.";
  const markdown = useMemo(() => {
    return (
      <section>
        <div>{heading}</div>
        <div>{description}</div>
        <div>_This content is rendered from JSX and Markdown combined._</div>
      </section>
    );
  }, [heading, description]);

  const reactContent = useRemark({
    markdown,
    stableMarkdown: true,
    components: {
      h1: "h2",
      strong: (props) => <strong style={{ color: "#e67e22" }} {...props} />,
      em: (props) => <em style={{ fontStyle: "italic", opacity: 0.8 }} {...props} />,
    },
  });

  return reactContent;
}

Remark Component

Use the <Remark> component for a declarative approach:

import React from "react";
import Remark from "react-remarkify";

export default function App() {
  const heading = "# Welcome to the App";
  const description = "This is a **React-powered** Markdown block.";

  return (
    <Remark
      components={{
        h1: "h2",
        strong: (props) => <strong style={{ color: "#e67e22" }} {...props} />,
        em: (props) => <em style={{ fontStyle: "italic", opacity: 0.8 }} {...props} />,
      }}
    >
      <section>
        <div>{heading}</div>
        <div>{description}</div>
        <div>_This content is rendered from JSX and Markdown combined._</div>
      </section>
    </Remark>
  );
}

API Reference

useRemark Hook

The useRemark hook accepts the following parameters:

| Parameter | Type | Required | Default | Description | | ----------------------- | --------------------------------------------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | markdown | React.ReactNode | Yes | - | The markdown content to be converted into React.js components. | | stableMarkdown | boolean | No | false | Skips expensive internal content analysis and relies on the referential identity of markdown. Enable this only if the provided markdown value is stable across renders, for example memoized with useMemo. If the reference changes, the content will be reprocessed. | | rehypePlugins | PluggableList | No | - | Plugins for rehype to extend functionality. | | rehypeReactOptions | RehypeReactOptions | No | - | Options for customizing the generated React.js components. | | remarkParseOptions | RemarkParseOptions | No | - | Parsing options for remark. | | remarkPlugins | PluggableList | No | - | Plugins for remark to enhance Markdown processing. | | remarkToRehypeOptions | RemarkRehypeOptions | No | - | Options for the remark to rehype transformation. | | components | Components | No | - | A mapping of HTML elements to custom React components, allowing customization of rendered Markdown elements. | | updateMode | UpdateMode | No | immediate | Controls how text changes are processed: immediate (updates instantly), throttle (updates at most every updateDelay ms, ideal for AI streaming), or debounce (waits updateDelay ms after changes stop, ideal for user typing). | | updateDelay | number (ms) | No | 0 | Delay for updateMode = throttle or debounce. Has no effect when updateMode is immediate. | | onError | Function | No | console.error | Callback to handle errors during the Markdown-to-React conversion process. |

Note: For performance reasons, the following options are treated as immutable after initialization: rehypePlugins, rehypeReactOptions, remarkParseOptions, remarkPlugins, remarkToRehypeOptions, components, and onError. Changing them dynamically will have no effect during the component's lifecycle.

Remark Component

The <Remark> component accepts the same options as useRemark, but you pass the markdown content as its children:

<Remark>{markdown}</Remark>

Types

Components

import { ComponentType, JSX } from "react";
type Components = { [Key in keyof JSX.IntrinsicElements]?: ComponentType<JSX.IntrinsicElements[Key] & { node?: Element }> | keyof JSX.IntrinsicElements };

PluggableList

import type { PluggableList } from "unified";

RehypeReactOptions

import type { Components } from "hast-util-to-jsx-runtime";

type RehypeReactOptions = { components?: Partial<Components> };

RemarkParseOptions

import type { Options } from "remark-parse";

type RemarkParseOptions = Options;

RemarkRehypeOptions

import type { Options } from "remark-rehype";

type RemarkRehypeOptions = Options;

UpdateMode

type UpdateMode = "immediate" | "throttle" | "debounce";

License

This project is licensed under the MIT License.