React Showdown: Markdown with Embedded Components

Common errors

• Error: Objects are not valid as a React child (found: object with keys {CustomComponent}). If you meant to render a collection of children, use an array instead.

  cause Incorrectly passing the `components` prop. The `components` prop expects an object where keys are the component names used in markdown and values are the React component functions themselves, not an array or a deeply nested object.
  fix Ensure the `components` prop is an object with direct references to your React components: `<MarkdownView components={{ YourComponent }} />`.

• TypeError: Cannot read properties of undefined (reading 'markdown') (or similar property access errors related to props)

  cause The required `markdown` prop was not provided or was `undefined` when rendering the `MarkdownView` component.
  fix Always pass a string value, even an empty one, to the `markdown` prop: `<MarkdownView markdown={myMarkdownString} />`.

• Markdown content appears truncated or parts are missing, especially after custom HTML-like tags.

  cause This typically occurs in versions prior to 2.1.0, or if `recognizeSelfClosing` is explicitly set to `false`, preventing Showdown from correctly parsing content after self-closing elements.
  fix Upgrade `react-showdown` to version 2.1.0 or newer. If upgrading isn't an option, or if the issue persists, ensure `options={{ recognizeSelfClosing: true }}` is passed to `MarkdownView`.

Warnings

• gotcha In `react-showdown` v2.1.0, the default value for the `showdown` configuration option `recognizeSelfClosing` was changed to `true`. This fixed an issue where content might be missing after a self-closing component. If you were explicitly setting `recognizeSelfClosing: false` or relying on the previous (buggy) default behavior, your rendered output might change.
  Fix: Review markdown content and converter options, especially if self-closing HTML-like tags (e.g., `<br/>`) are used. If previous behavior is desired, explicitly set `options={{ recognizeSelfClosing: false }}`.
• breaking This library requires React version 16 or newer as a peer dependency. Using it with older React versions (e.g., React 15) will result in installation errors or runtime failures due to incompatible React APIs.
  Fix: Upgrade your project's React dependency to version 16 or higher. Use `npm install react@^16.0.0 react-dom@^16.0.0` or `yarn add react@^16.0.0 react-dom@^16.0.0`.

Install

• npm install react-showdown npm
• yarn add react-showdown yarn
• pnpm add react-showdown pnpm

Imports

• MarkdownView
  wrong:

  import { MarkdownView } from 'react-showdown';

  correct:

  import MarkdownView from 'react-showdown';

  MarkdownView is the default export and main component for rendering Markdown.
• ConverterOptions
  wrong:

  import { ConverterOptions } from 'react-showdown';

  correct:

  import type { ConverterOptions } from 'react-showdown';

  Used for type-checking the options prop passed to MarkdownView. Prefer 'import type' for type-only imports in TypeScript.
• Flavor
  wrong:

  import { Flavor } from 'react-showdown';

  correct:

  import type { Flavor } from 'react-showdown';

  Used for type-checking the 'flavor' prop, which allows setting predefined Showdown configurations. Prefer 'import type' for type-only imports.

Quickstart

Demonstrates rendering basic Markdown with options and embedding a custom React component within Markdown text.

import React from 'react';
import MarkdownView from 'react-showdown';

function CustomComponent({ name }: { name: string }) {
  return <span style={{ color: 'blue', fontWeight: 'bold' }}>Hello {name}!</span>;
}

export default function App() {
  const basicMarkdown = `
# Welcome to React Showdown :wave:

This is a simple markdown example with a table and emojis.

| Header 1 | Header 2 |
|----------|----------|
| Cell A1  | Cell B1  |
| Cell A2  | Cell B2  |
`;

  const markdownWithComponent = `
# Embedding React Components

Here's a custom component: <CustomComponent name="World" />

You can pass props and define complex logic within them.
`;

  return (
    <div>
      <h2>Basic Markdown Render:</h2>
      <MarkdownView
        markdown={basicMarkdown}
        options={{ tables: true, emoji: true, simpleLineBreaks: true }}
        className="markdown-output"
      />

      <h2>Markdown with Custom Component:</h2>
      <MarkdownView
        markdown={markdownWithComponent}
        components={{ CustomComponent }}
        className="markdown-output"
      />
    </div>
  );
};