Higher Order Component to add MDX syntax support to [react-markdown][react-markdown].
npm install react-markdown-with-mdxHigher Order Component to add MDX syntax support to [react-markdown][react-markdown].
- What is this?
- When should I use this?
- Install
- Use
- API
- Examples
- Security
- Compatibility
- Related
- License
This package provides a Higher Order Component that enhances [react-markdown][react-markdown] with MDX JSX syntax support.
The HOC processes markdown content to:
- Parse MDX syntax using [remark-mdx][remark-mdx]
- Transform MDX elements into React components
- Preserve all existing [react-markdown][react-markdown] functionality
Use this package when you want to:
- Add MDX component support to existing [react-markdown][react-markdown] implementations
- Use MDX component syntax without full MDX compilation
- Render MDX component content at runtime without executing arbitrary Javascript
Don't use this package if you need full MDX features like imports, exports, or expression execution - use [@mdx-js/mdx][mdx] instead.
For a technical deep dive see here.
This package is ESM only.
``sh`
npm install react-markdown-with-mdx
You'll also need [react][react] and [react-markdown][react-markdown] as peer dependencies:
`sh`
npm install react react-markdown
`jsx
import React from 'react'
import Markdown from 'react-markdown'
import { withMdx } from 'react-markdown-with-mdx'
// Create enhanced component
const MarkdownWithMdx = withMdx(Markdown)
// Define your custom components
const components = {
Card: ({ children, variant = 'default' }) => (
}>{children}}>{message}// Use with MDX JSX syntax
const markdown =
This is regular markdown with bold text.
function App() {
return (
{markdown}
)
}
`
Higher Order Component that enhances a react-markdown component with MDX support.
#### Parameters
- MarkdownComponent (React.ComponentType) — The react-markdown component to enhance
#### Returns
Enhanced component (React.ComponentType) with MDX support.
Extended options interface that includes all react-markdown options plus:
- remarkMdxPlugins (PluggableList, optional) — Additional remark plugins specifically for MDX processing
All other options from [react-markdown][react-markdown] are supported, including:
- components — React components to use for renderingremarkPlugins
- — Additional remark pluginsrehypePlugins
- — Additional rehype pluginsremarkRehypeOptions
- — Options for remark-rehype
Component type for creating a components mapping object.
` (Component: React.FC , validator: ZodType ) => React.FCtypescript`
mdxComponent
Optional validation helper function that takes a functional component along with a zod validator that ensures the react-markdown props are mapped to the provided component.
`tsx
interface CustomCardProps extends React.PropsWithChildren {
id: string
title: string
type?: "standard" | "primary"
}
const CustomCard: React.FC
id,
title,
type,
children
}) {
return
{title}
{children}
}
const components: MdxComponents = {
CustomCard: mdxComponent(CustomCard,
z.object({
id: z.string(),
title: z.string(),
type: z.union([z.literal("standard"), z.literal("primary")]).optional(),
children: z.any()
})
)
}
`
`jsx
import { withMdx } from 'react-markdown-with-mdx'
import Markdown from 'react-markdown'
const MarkdownWithMdx = withMdx(Markdown)
const components = {
CustomCard: ({ children, primary }) => (
const content =
Hello There!
`
`jsx
const components = {
Card: ({ title, children }) => (
{title}
{children}
),
Link: ({ url, children }) => {children}
}
const content =
This is a card with markdown content.
Action
`jsx
const MarkdownWithMdx = withMdx(Markdown)
const customRemarkPlugin = () => (tree) => {
// Your custom remark plugin logic
}
remarkPlugins={[customRemarkPlugin]}
remarkMdxPlugins={[/ MDX-specific plugins /]}
>
{content}
`
This package maintains the security model of [react-markdown][react-markdown]:
- Only components explicitly provided in the components prop are allowed
- JSX components not in the allowlist are completely removed
- All other security features of [react-markdown][react-markdown] are preserved
`jsx
// Only Card is allowed, script will be removed
const components = { Card: MyCard }
const unsafeContent =
// Result: Only the Card renders, script is removed
This package works with:
- [React][react] 18+
- [react-markdown][react-markdown] 10+
- [Node.js][node] 18+
It uses ES modules and requires a modern JavaScript environment.
- [react-markdown][react-markdown] — The base markdown renderer
- [remark-mdx][remark-mdx] — MDX syntax support for remark
- [remark-unravel-mdx][remark-unravel-mdx] — Unravels MDX JSX to remove unnecessary paragraph wrappers
- [rehype-mdx-elements][rehype-mdx-elements] — Converts MDX elements to React components
- [@mdx-js/mdx][mdx] — Full MDX compiler
[MIT][license] © [Tim Etler][author]
[license]: LICENSE.md
[author]: https://github.com/etler
[react]: https://reactjs.org/
[react-markdown]: https://github.com/remarkjs/react-markdown
[remark-mdx]: https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx
[remark-unravel-mdx]: https://github.com/etler/remark-unravel-mdx
[rehype-mdx-elements]: https://github.com/etler/rehype-mdx-elements
[mdx]: https://github.com/mdx-js/mdx
[node]: https://nodejs.org/