@domeadev/react-markdown

A lightweight, customizable React component for rendering Markdown content with TypeScript support and extensible rendering.

Features

• 🚀 Fast and Lightweight: Built on top of marked for efficient parsing
• 🎨 Fully Customizable: Override any element renderer with custom React components
• 🔧 TypeScript Support: Full type safety with comprehensive TypeScript definitions
• 🧩 Extensible: Support for custom extensions and element types
• 📝 GFM Support: GitHub Flavored Markdown support out of the box
• 📚 Storybook: Interactive examples and documentation

📖 Documentation & Examples

View Live Storybook Documentation →

Explore interactive examples, API documentation, and usage patterns in our Storybook deployment.

Installation

npm

npm install @domeadev/react-markdown

yarn

yarn add @domeadev/react-markdown

pnpm

pnpm add @domeadev/react-markdown

Quick Start

import { ReactMarkdown, useReactMarkdown } from "@domeadev/react-markdown";

function MyComponent() {
  const markdown = `
# Hello World

This is **bold** text and this is *italic* text.

- List item 1
- List item 2
- [ ] Todo item
- [x] Completed item

[Link to example](https://example.com)
  `;

  const { elements, renders } = useReactMarkdown(markdown);

  return <ReactMarkdown elements={elements} renders={renders} />;
}

API Reference

useReactMarkdown Hook

The main hook for parsing markdown content.

const { elements, renders } = useReactMarkdown(markdown, options);

Parameters

• markdown (string): The markdown content to parse
• options (optional): Configuration options

Options

interface ReactMarkdownOptions {
  /** Enable GitHub Flavored Markdown @default true */
  gfm?: boolean;
  /** Handle line breaks */
  breaks?: boolean;
  /** Custom extensions */
  extensions?: ReactMarkdownExtension[];
  /** Override default element renderers */
  renders?: Partial<DefaultElementRenders>;
}

ReactMarkdown Component

The main component for rendering parsed markdown elements.

<ReactMarkdown elements={elements} renders={renders} />

Props

• elements: Parsed markdown elements from useReactMarkdown
• renders: Element renderers (default + custom overrides)

Customizing Renderers

You can customize how any markdown element is rendered:

import { ReactMarkdown, useReactMarkdown } from "@domeadev/react-markdown";

function CustomMarkdown() {
  const markdown = "# Custom Heading\n\nThis is a **bold** paragraph.";

  const { elements } = useReactMarkdown(markdown, {
    renders: {
      // Custom heading renderer
      heading: ({ element, children }) => {
        const headingElement = element as MarkdownHeadingElement;
        return (
          <h1 className={`custom-h${headingElement.depth}`}>🎉 {children}</h1>
        );
      },
      // Custom paragraph renderer
      paragraph: ({ children }) => (
        <p className="custom-paragraph">{children}</p>
      ),
      // Custom strong (bold) renderer
      strong: ({ children }) => (
        <span className="font-bold text-blue-600">{children}</span>
      ),
    },
  });

  return <ReactMarkdown elements={elements} renders={renders} />;
}

Available Element Types

The following markdown elements are supported with default renderers:

| Element | Description | Custom Props | | -------------- | ----------------------- | -------------------------------------- | | heading | H1-H6 headings | depth: 1-6 | | paragraph | Paragraph text | - | | list | Ordered/unordered lists | ordered: boolean | | list_item | List items | task: boolean, checked?: boolean | | link | Links | href: string | | image | Images | src: string, alt: string | | code | Code blocks | lang?: string | | codespan | Inline code | - | | strong | Bold text | - | | emphasis | Italic text | - | | delete | Strikethrough text | - | | blockquote | Block quotes | - | | table | Tables | align: TableAlign[] | | table_header | Table header | - | | table_body | Table body | - | | table_row | Table row | - | | table_cell | Table cell | header: boolean, align: TableAlign | | br | Line break | - | | hr | Horizontal rule | - | | text | Plain text | - | | space | Whitespace | - |

Creating Extensions

You can create custom extensions to handle new markdown syntax:

import { ReactMarkdownExtension } from "@domeadev/react-markdown";

// Example: Custom mention extension
const mentionExtension: ReactMarkdownExtension = {
  name: "mention",
  level: "inline",
  start(src: string) {
    return src.indexOf("@");
  },
  tokenizer(src: string) {
    // Match @username pattern (letters, numbers, underscore, hyphen)
    const rule = /^@([a-zA-Z0-9_-]+)/;
    const match = rule.exec(src);

    if (match) {
      return {
        type: "mention",
        raw: match[0],
        username: match[1],
      };
    }
    return undefined;
  },
  parser: (token) => ({
    type: "mention",
    text: token.raw,
    username: token.username,
  }),
  render: ({ element }) => <span className="mention">@{element.username}</span>,
};

const { elements, renders } = useReactMarkdown(markdown, {
  extensions: [mentionExtension],
});

Advanced Usage

With Custom Styling

import { ReactMarkdown, useReactMarkdown } from "@domeadev/react-markdown";
import "./markdown-styles.css";

function StyledMarkdown({ content }: { content: string }) {
  const { elements, renders } = useReactMarkdown(content, {
    renders: {
      heading: ({ element, children }) => {
        const HeadingTag = `h${element.depth}` as keyof JSX.IntrinsicElements;
        return (
          <HeadingTag className={`heading-${element.depth} mb-4 font-bold`}>
            {children}
          </HeadingTag>
        );
      },
      code: ({ element }) => (
        <pre className="bg-gray-100 p-4 rounded-lg overflow-x-auto">
          <code className={`language-${element.lang || "text"}`}>
            {element.text}
          </code>
        </pre>
      ),
      link: ({ element, children }) => (
        <a
          href={element.href}
          className="text-blue-600 hover:text-blue-800 underline"
          target="_blank"
          rel="noopener noreferrer"
        >
          {children}
        </a>
      ),
    },
  });

  return (
    <div className="prose prose-lg max-w-none">
      <ReactMarkdown elements={elements} renders={renders} />
    </div>
  );
}

With Task Lists

function TaskListExample() {
  const todoMarkdown = `
## My Todo List

- [x] Complete the documentation
- [x] Add TypeScript support
- [ ] Write more tests
- [ ] Add more examples
  `;

  const { elements, renders } = useReactMarkdown(todoMarkdown, {
    renders: {
      list_item: ({ element, children }) => (
        <li className="flex items-center gap-2">
          {element.task && (
            <input
              type="checkbox"
              checked={element.checked}
              className="form-checkbox h-4 w-4 text-blue-600"
              readOnly
            />
          )}
          <span className={element.checked ? "line-through text-gray-500" : ""}>
            {children}
          </span>
        </li>
      ),
    },
  });

  return <ReactMarkdown elements={elements} renders={renders} />;
}

Development

Build

pnpm build

Test

pnpm test

Storybook Development

Start the development server:

pnpm storybook

Build Storybook for production:

pnpm build-storybook

The Storybook documentation is automatically deployed to GitHub Pages on every push to the main branch.

GitHub Pages Setup

For repository maintainers, the GitHub Pages deployment is handled automatically via GitHub Actions. To enable this:

1. Go to your repository's Settings → Pages
2. Set Source to "GitHub Actions"
3. The workflow will automatically deploy Storybook to https://[username].github.io/[repository-name]/

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Dependencies

• marked - Fast markdown parser
• @domeadev/react-elements-renderer - Efficient React element rendering

Related Packages

• @domeadev/react-elements-renderer - The underlying element rendering engine