React Native Markdown Renderer

A 100% CommonMark-compatible markdown renderer for React Native using native components (not WebView). All elements are rendered as native React Native components that can be overwritten when needed.

npm: react-native-markdown-renderer | GitHub: mientjan/react-native-markdown-renderer | Changelog: CHANGELOG.md

Installation

npm install react-native-markdown-renderer

Requirements

| Dependency | Version | | ------------ | ---------- | | React | >= 18.0.0 | | React Native | >= 0.73.0 |

Basic Usage

import React from 'react';
import Markdown from 'react-native-markdown-renderer';

const App = () => (
  <Markdown>
    {`# Hello World

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

- Item 1
- Item 2
`}
  </Markdown>
);

Examples

The example/ directory contains an Expo app with multiple screens demonstrating key features:

| Screen | Description | Source | |--------|-------------|--------| | Basic Markdown | Default rendering | BasicExample.tsx | | From .md File | Load markdown from a file asset | MarkdownFileExample.tsx | | Custom Styles | Override default styles | CustomStylesExample.tsx | | Custom Rules | Replace render rules | CustomRulesExample.tsx | | Custom Renderer | Provide a custom AstRenderer | CustomRendererExample.tsx |

To run the example app:

cd example
npm install
npx expo start

TypeScript Support

This library is written in TypeScript and ships with full type definitions.

import Markdown, {
  AstRenderer,
  renderRules,
  styles,
  PluginContainer,
  type MarkdownProps,
  type RenderRules,
  type ASTNode,
  type RenderFunction,
  type MarkdownStyles,
} from 'react-native-markdown-renderer';

Custom Styles

By default, custom styles are deep-merged with the built-in defaults — so you only need to specify properties you want to override. Set mergeStyle={false} to replace entire style objects instead.

import Markdown from 'react-native-markdown-renderer';

const customStyles = {
  heading1: { fontSize: 40, color: '#333' },  // keeps default fontWeight, lineHeight, etc.
  strong: { fontWeight: '800' },
  paragraph: { marginVertical: 8 },
};

const App = () => (
  <Markdown style={customStyles}>
    {'# Styled Heading\n\n**Bold text** in a paragraph.'}
  </Markdown>
);

Custom Render Rules

import React from 'react';
import { Text, View } from 'react-native';
import Markdown from 'react-native-markdown-renderer';
import type { ASTNode, RenderRules } from 'react-native-markdown-renderer';

const customRules: Partial<RenderRules> = {
  heading1: (node: ASTNode, children, parent, styles) => (
    <View key={node.key} style={{ backgroundColor: '#eee', padding: 10 }}>
      <Text style={{ fontSize: 28 }}>{children}</Text>
    </View>
  ),
};

const App = () => (
  <Markdown rules={customRules}>
    {'# Custom Heading'}
  </Markdown>
);

Plugins

This library uses markdown-it as its parser. Any markdown-it plugin can be used:

import Markdown, { PluginContainer } from 'react-native-markdown-renderer';
import markdownItCheckbox from 'markdown-it-checkbox';

const plugins = [new PluginContainer(markdownItCheckbox)];

const App = () => (
  <Markdown plugins={plugins}>
    {'- [ ] Unchecked\n- [x] Checked'}
  </Markdown>
);

Handling Links

By default, links open via Linking.openURL(). Use the onLinkPress prop to customize:

const App = () => (
  <Markdown onLinkPress={(url) => {
    console.log('Link pressed:', url);
    // return nothing to prevent default behavior
  }}>
    {'[Visit Example](https://example.com)'}
  </Markdown>
);

Image Validation

Control which image URL schemes are allowed. Images with unrecognized schemes get the defaultImageHandler prepended, or are skipped entirely when set to null:

<Markdown
  allowedImageHandlers={['https://', 'data:image/png;base64']}
  defaultImageHandler={null}  // skip images that don't match
>
  {'![photo](https://example.com/photo.png)'}
</Markdown>

Preview Mode

Limit how many top-level elements render — useful for content previews:

import { Text } from 'react-native';

<Markdown
  maxTopLevelChildren={3}
  topLevelMaxExceededItem={<Text key="more">Read more...</Text>}
>
  {longMarkdownContent}
</Markdown>

Props

| Prop | Type | Default | Description | | ---- | ---- | ------- | ----------- | | children | string \| string[] | — | Markdown content to render (required) | | rules | RenderRules | — | Custom render rules for element types | | style | Partial<MarkdownStyles> | — | Custom styles (merged with defaults by default) | | mergeStyle | boolean | true | Deep-merge custom styles with defaults per key. Set false for shallow replace | | onLinkPress | (url: string) => boolean \| void | — | Custom link press handler. Falls back to Linking.openURL() | | renderer | AstRenderer \| ((nodes) => ReactElement) | — | Fully custom renderer (overrides rules/style) | | markdownit | MarkdownIt | MarkdownIt({ typographer: true }) | Custom markdown-it instance | | plugins | PluginContainer[] | [] | markdown-it plugins | | debugPrintTree | boolean | false | Log the AST tree structure to the console | | maxTopLevelChildren | number \| null | null | Limit rendered top-level children (preview mode) | | topLevelMaxExceededItem | ReactNode | <Text>...</Text> | Shown when maxTopLevelChildren is exceeded | | allowedImageHandlers | string[] | ['data:image/png;base64', ..., 'https://', 'http://'] | Allowed image URL prefixes | | defaultImageHandler | string \| null | 'http://' | Prepended to images with unrecognized schemes. null to skip |

Syntax Support

• Headings (1-6)
• Emphasis (bold, italic, ~~strikethrough~~)
• Blockquotes
• Lists (ordered and unordered)
• Code (inline and blocks)
• Tables
• Links
• Images
• Horizontal rules
• Typographic replacements
• Plugins for extra syntax support via markdown-it plugins

Documentation

For comprehensive documentation, visit the Wiki:

• Getting Started
• Custom Styles
• Custom Rules
• Custom Renderer
• Plugins
• API Reference
• Migration from v3

What's New in v4.1.0

• onLinkPress prop — custom link press handler instead of hardcoded Linking.openURL()
• mergeStyle prop (default true) — deep-merge custom styles with defaults per key
• debugPrintTree prop — log AST tree structure to console for debugging
• maxTopLevelChildren + topLevelMaxExceededItem — preview mode to limit rendered children
• allowedImageHandlers + defaultImageHandler — validate image URLs before rendering
• Image accessibility — accessibilityLabel from image alt text
• Hardbreak fix — renders as <Text>{'\n'}</Text> instead of <View> (fixes Android crash inside Text)
• Code block fix — trims trailing newline from code_block and fence content
• Ordered list fix — respects the start attribute (e.g. 57. foo renders as 57)

Migration from v3 to v4

Breaking Changes

1. Minimum React 18.0.0 (was 16.2.0)
2. Minimum React Native 0.73.0 (was 0.50.4)
3. react-native-fit-image removed - The default image render rule now uses React Native's built-in <Image>. If you need auto-sizing, provide a custom image render rule.
4. prop-types removed - Use TypeScript for type checking.
5. Class component replaced with function component - The <Markdown> component is now a function component. Any code relying on class refs will break.
6. markdown-it upgraded from ^8 to ^14 - Custom markdown-it plugins should verify compatibility.
7. Package entry points changed - main points to lib/commonjs/, module to lib/module/, types to lib/typescript/.

License

MIT