**[rehype][]** plugin to convert MDX JSX elements to regular HTML elements.
npm install rehype-mdx-elements[rehype][] plugin to convert MDX JSX elements to regular HTML elements.
* What is this?
* When should I use this?
* Install
* Use
* API
* rehypeMdxElements(options?)
* Options
* Types
* Security
* Related
* License
This package is a [unified][] ([rehype][]) plugin to convert MDX JSX element
nodes to regular HTML elements that can be handled by component mapping.
unified is a project that transforms content with abstract syntax trees
(ASTs).
rehype adds support for HTML to unified.
MDX is markdown that supports JSX.
hast is the HTML AST that rehype uses.
This is a rehype plugin that transforms MDX JSX elements in the hast.
This plugin is useful when you want to render arbitrary markdown with custom
component support while maintaining security.
Unlike full MDX implementations that support JSX expressions and imports,
this plugin only processes JSX elements with literal attributes, making it
safe for untrusted content.
Use this plugin when you need to:
* Render arbitrary markdown with custom components
* Preserve case-sensitive component names and attributes
* Avoid the security risks of full JSX expression evaluation
This package is [ESM only][esm].
``sh`
npm install rehype-mdx-elements
`sh`
yarn add rehype-mdx-elements
`html`
example.mdx:
`mdHello
Some text with
`
example.tsx:
`tsx
import {readFileSync} from 'node:fs'
import {unified} from 'unified'
import remarkParse from 'remark-parse'
import remarkMdx from 'remark-mdx'
import remarkRehype from 'remark-rehype'
import {rehypeMdxElements} from 'rehype-mdx-elements'
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
import {Fragment, jsx, jsxs} from 'react/jsx-runtime'
import React from 'react'
// Component definitions
const Button = (props: {variant?: string; children?: React.ReactNode}) => (
)
const Alert = (props: {type?: string; children?: React.ReactNode}) => (
}>
{props.children}
const components = {Button, Alert}
const file = readFileSync('example.mdx')
const processor = unified()
.use(remarkParse)
.use(remarkMdx)
.use(remarkRehype, {passThrough: ['mdxJsxFlowElement', 'mdxJsxTextElement']})
.use(rehypeMdxElements, {
allowedElements: Object.keys(components)
})
const tree = processor.parse(file)
const transformedTree = await processor.run(tree)
// Convert to React elements
const reactElement = toJsxRuntime(transformedTree, {
Fragment,
jsx,
jsxs,
components
})
console.log(reactElement)
`
Running example.tsx produces JSX runtime elements with the following content:
` Some text with jsx`
<>
Hello
Convert MDX JSX elements to regular HTML elements.
###### Parameters
* options ([Options][api-options], optional)
— configuration
###### Returns
Transform ([Transformer][unified-transformer]).
###### Fields
* allowedElements (Array, optional)disallowedElements
list of allowed component names, case insensitive.
If provided, only these components will be converted to HTML elements.
Other JSX elements will be removed.
* (Array, optional)
list of disallowed component names, case insensitive.
These components will be removed from the output.
MDX JSX elements can contain arbitrary JavaScript expressions, which is
dangerous when executed in an untrusted environment.
This plugin helps mitigate security risks by:
1. Only converting static JSX elements and omiting imports and expressions which could contain arbitrary code
2. Only converting static JSX attributes with string or void values
3. Allowing you to specify which component names are allowed or disallowed
* [remark-mdx][remark-mdx] adds support for MDX syntaxremark-rehype`][remark-rehype] transforms markdown to HTML
* [
[MIT][license] © [Tim Etler][author]
[license]: LICENSE.md
[author]: https://github.com/etler
[api-options]: #options
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[rehype]: https://github.com/rehypejs/rehype
[remark-mdx]: https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx
[remark-rehype]: https://github.com/remarkjs/remark-rehype
[unified]: https://github.com/unifiedjs/unified
[unified-transformer]: https://github.com/unifiedjs/unified#transformer