Markdown renderer for React Native
npm install @docren/react-native-markdown!NPM License
!NPM Version
!runs with expo
!npm
A flexible and performant Markdown renderer for React Native, powered by MDAST. Supports custom styling, nested elements, and extendable render rules for full control over output.
https://github.com/user-attachments/assets/7e07a865-bccd-4961-b696-0b17935bbcc9
- 📄 CommonMark-Compliant – Parses and renders Markdown based on the CommonMark spec
- 🧩 GFM Support – Extend Markdown with GitHub Flavored Markdown features via pluggable extensions.
- ⚛️ React Native First – Designed specifically for rendering Markdown in React Native environments
- 🎯 AST-Based Rendering – Fine-grained control using custom render rules powered by MDAST nodes
- 🛠️ Fully Customizable – Customize how each Markdown element is rendered with flexible render rules
- 🧠 Lightweight & Tree-Shakeable – Minimal footprint with no bundled syntax highlighters
- 🔐 TypeScript First – Strong typing throughout for safer and more predictable code
_Markdown_ – Render Markdown with customizable components, AST access, and full control over rendering behavior.
This package is inspired by react-native-markdown-display — many thanks to the original author for laying the groundwork for Markdown rendering in React Native.
We’ve built on this foundation with a fully type-safe architecture, swapped in the lighter and more modern mdast-util-from-markdown parser for better performance and maintainability, and added extended support for more Markdown elements, custom rendering, and advanced features.
NPM
``sh`
npm install @docren/react-native-markdown
Yarn
`sh`
yarn add @docren/react-native-markdown
PNPM
`sh`
pnpm add @docren/react-native-markdown
`jsx
import { View, StyleSheet, ScrollView } from 'react-native';
import { Markdown } from '@docren/react-native-markdown';
export default function App() {
return (
}
}
/>
);
}
export default App;
`
For more detailed usage ⬇️
The component takes the following props.
| Prop | Type | Default | Description |
| ------------------- | --------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| markdon | string \| Uint8Array | N/A | required The Markdown content to render. Accepts plain strings or .md file contents as Uint8Array. |false
| style | StyleMap \| null | source | Styles applied to Markdown elements. Pass a map of styles keyed by Markdown element types. |
| mergeStyle | boolean | true | Whether to merge default styles with the user-provided style map. If , only your styles are used. |
| renderRules | RenderRules | source | Customize how specific Markdown elements are rendered using an object of render functions. Merged by default. |
| listBulletStyle | 'disc' \| 'dash' | 'disc' | Defines the default bullet style for unordered lists (• or –). |
| customBulletElement | ReactElement \| null | N/A | Override the default list bullet with a custom React element. Applies to all unordered list items. |
| onLinkPress | (url: string) => void | N/A | Callback invoked when a link is pressed. Useful for navigation or analytics. |
| extensions | Extension[] | [] | Extend or modify Markdown parsing by providing custom MDAST extensions. Useful for GFM or custom syntax. To know more |
| debug | boolean | false | Enable debug logs during parsing and rendering for development purposes. |
- [x] blockquote
- [x] break
- [x] code
- [x] emphasis
- [x] definition
- [x] heading
- [x] heading1
- [x] heading3
- [x] heading4
- [x] heading2
- [x] heading5
- [x] heading6
- [x] image
- [x] imageReference
- [x] inlineCode
- [x] link
- [x] linkReference
- [x] list
- [x] listItem
- [x] paragraph
- [x] root
- [x] strong
- [x] text
- [x] thematicBreak
- [ ] strikethrough (Planned)
- [ ] table (Planned)
- [ ] tableCell
- [ ] tableRow
- [ ] html (Not planned)
- [ ] yaml (Not planned)
Text styles follow a cascading approach, similar to how CSS works. Global styles can be set using the root style, which will apply across most Markdown elements, while still allowing you to override specific styles on individual elements when needed.
Keep in mind: the text style does not affect all text nodes—especially things like list bullets. If you want to apply a consistent style (e.g. color or font) to all text, it’s better to define it in the root style instead.
#### Styles
Styles allow you to customize the appearance of specific Markdown elements, overriding the default styling behavior,
Default styling.
> By default, your styles are merged with the built-in styles. To override them completely, refer to the mergeStyle prop.
`jsx`
export default function App() {
return (
styles={{
blockquote: {
backgroundColor: '#cad8ee',
borderRadius: 12,
},
}}
/>
);
}
#### Rules
Rules let you define how specific Markdown elements should be rendered. You can find the default implementation here.
Note: When defining rules, make sure to assign a unique key to each component. You can use a custom value or the key provided in the node property.
> ℹ️ You don’t need to define rules for definition, linkReference, or imageReference, as these are internally resolved to link and image. You can still use them in your Markdown content. If you need customization, override the render rules for link and image.
> If you’re using this package with Expo, it’s recommended to use expo-image for rendering images.
`jsx
import {Image} from 'expo-image'
export default function App() {
const mdxString =
!Alt text
return (
renderRules={{
image: ({ node }) => (
source={{ uri: node.url }}
alt={node.alt ?? ""}
style={{ width: "100%", height: 300, borderRadius: 8 }}
/>
),
}}
/>
);
}
`
#### Syntax Highlighing
This package does not include built-in syntax highlighting, as it aims to remain lightweight. However, you can integrate external libraries like react-native-syntax-highlighter or react-native-code-highlighter for that functionality.
Once integrated, you can apply syntax highlighting by overriding the renderRule.code function.
An example implementation can be found in the included example app.
Syntax highlighting render rule
`jsx
import CodeHighlighter from 'some-syntax-highlighting-package'
renderRules={{
code: ({ node }) => (
hljsStyle={atomOneDarkReasonable} //highlight.js theme
language={node.lang || 'plaintext'}
scrollViewProps={{
bounces: false,
contentContainerStyle: styles.codeContentContainer,
}}
textStyle={styles.codeTextStyle}
>
{node.value}
),
}}
/>
`
#### Handling Link
By default, links are handled by Linking from react-native. ie,
`tsx
import { Linking } from 'react-native';
Linking.openURL(url);
`
You can override this behavior in one of two ways:
Using the onLinkPress callback
`jsx
export default function App() {
const mdxString = Link to Google
const onLinkPress = (url: string) => {
// Handle link press, e.g., open in a web browser or navigate to a screen
console.log('Link pressed:', url);
};
return (
);
}
`
Providing a custom renderRule.link implementation
To override the default link behavior, you can use a custom renderRule.link. If you’re using Expo, it’s recommended to use expo-router for internal links and expo-linking for external links.
`tsx
export default function Screen() {
const markdown =
Explore
Google
;
const router = useRouter();
const handleLinkPress = (url: string) => {
if (!url.startsWith('/')) {
// If the URL does not start with '/', treat it as an external link
// and open it in the default browser.
return Linking.openURL(url);
}
router.push(url as Href);
};
const rules: RenderRules = {
link: ({ node, children }) => {
return (
style={{ color: 'blue', textDecorationLine: 'underline' }}
onPress={() => handleLinkPress(node.url)}
>
{children}
);
},
};
return (
);
}
``
#### All rules and their associated styles
Most rules and styles share the same names, so refer to the Syntax Support section for the complete list of available rules. Any exceptions with different naming are listed below.
When in doubt check the default styling and default render rules
> No rules or styles are provided for definition, linkReference, and imageReference, as they are handled internally as link and image, as mentioned above.
| Render Rule | Style | Note |
| ----------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| heading | heading1 \| heading2 \| heading3 \| heading4 \| heading5 \| heading6 | For a single heading render rule, there are six style variations corresponding to the different heading levels (h1 through h6). |
| listItem | listItem, listBullet, listItemContent | listItem – Style for the container that wraps both the bullet and the content. listBullet – Style for the default bullet used in unordered lists ( • or –). [Not applicablefor custom bullet element] listItemContent – Style for the content portion of the list item. |
- Themed Styling (Dark / light Mode)
- Table Support
- react-native-markdown-display
See the contributing guide to learn how to contribute to the repository and the development workflow.
This project is licensed under the MIT License.