Docs / Using MDX
This article explains how to use MDX files in your project. It shows how you can pass props and how to import, define, or pass components. See § Getting started for how to integrate MDX into your project. To understand how the MDX format works, we recommend that you start with § What is MDX.
An integration compiles MDX syntax to JavaScript. Say we have an MDX document, example.mdx
:
export function Thing() {
return <>World</>
}
# Hello <Thing />
That’s roughly turned into the following JavaScript. The below might help to form a mental model:
/* @jsxRuntime automatic @jsxImportSource react */
export function Thing() {
return <>World</>
}
export default function MDXContent() {
return <h1>Hello <Thing /></h1>
}
Some observations:
MDXContent
) is exportedThe actual output is:
import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'
export function Thing() {
return _jsx(_Fragment, {children: 'World'})
}
function _createMdxContent(props) {
const _components = {h1: 'h1', ...props.components}
return _jsxs(_components.h1, {children: ['Hello ', _jsx(Thing, {})]})
}
export default function MDXContent(props = {}) {
const {wrapper: MDXLayout} = props.components || {}
return MDXLayout
? _jsx(MDXLayout, {...props, children: _jsx(_createMdxContent, {...props})})
: _createMdxContent(props)
}
Some more observations:
{components: {wrapper: MyLayout}}
to wrap all content{components: {h1: MyComponent}}
to use something else for the heading† MDX is not coupled to React. You can also use it with Preact, Vue, Emotion, Theme UI, etc. Both the classic and automatic JSX runtimes are supported.
We just saw that MDX files are compiled to components. You can use those components like any other component in your framework of choice. Take this file:
# Hi!
It could be imported and used in a React app like so:
import React from 'react'
import ReactDom from 'react-dom'
import Example from './example.mdx' // Assumes an integration is used to compile MDX -> JS.
const root = ReactDom.createRoot(document.getElementById('root'))
root.render(<Example />)
The main content is exported as the default export. All other values are also exported. Take this example:
export function Thing() {
return <>World</>
}
# Hello <Thing />
It could be imported in the following ways:
// A namespace import to get everything:
import * as everything from './example.mdx' // Assumes an integration is used to compile MDX -> JS.
console.log(everything) // {Thing: [Function: Thing], default: [Function: MDXContent]}
// Default export shortcut and a named import specifier:
import Content, {Thing} from './example.mdx'
console.log(Content) // [Function: MDXContent]
console.log(Thing) // [Function: Thing]
// Import specifier with another local name:
import {Thing as AnotherName} from './example.mdx'
console.log(AnotherName) // [Function: Thing]
In § What is MDX, we showed that JavaScript expressions, inside curly braces, can be used in MDX:
import {year} from './data.js'
export const name = 'world'
# Hello {name.toUpperCase()}
The current year is {year}
Instead of importing or defining data within MDX, data can also be passed to MDXContent
. The passed data is called props
. Take for example:
# Hello {props.name.toUpperCase()}
The current year is {props.year}
This file could be used as:
import Example from './example.mdx' // Assumes an integration is used to compile MDX -> JS.
// Use a `createElement` call:
React.createElement(Example, {name: 'Venus', year: 2021})
// Use JSX:
<Example name="Mars" year={2022} />
There is one special prop: components
. It takes an object mapping component names to components. Take this example:
# Hello *<Planet />*
It can be imported from JavaScript and passed components like so:
import Example from './example.mdx' // Assumes an integration is used to compile MDX -> JS.
<Example
components={{
Planet() {
return <span style={{color: 'tomato'}}>Pluto</span>
}
}}
/>
You don’t have to pass components. You can also define or import them within MDX:
import {Box, Heading} from 'rebass'
MDX using imported components!
<Box>
<Heading>Here’s a heading</Heading>
</Box>
Because MDX files are components, they can also import each other:
import License from './license.md' // Assumes an integration is used to compile MDX -> JS.
import Contributing from './docs/contributing.mdx'
# Hello world
<License />
---
<Contributing />
Here are some other examples of passing components:
<Example
components={{
// Map `h1` (`# heading`) to use `h2`s.
h1: 'h2',
// Rewrite `em`s (`*like so*`) to `i` with a goldenrod foreground color.
em(props) {
return <i style={{color: 'goldenrod'}} {...props} />
},
// Pass a layout (using the special `'wrapper'` key).
wrapper({components, ...rest}) {
return <main {...rest} />
},
// Pass a component.
Planet() {
return 'Neptune'
},
// This nested component can be used as `<theme.text>hi</theme.text>`
theme: {
text(props) {
return <span style={{color: 'grey'}} {...props} />
}
}
}}
/>
The following keys can be passed in components
:
h1
for # heading
(see § Table of components for examples)wrapper
, which defines the layout (but a local layout takes precedence)*
anything else that is a valid JavaScript identifier (foo
, Quote
, _
, $x
, a1
) for the things you write with JSX (like <So />
or <like.so />
, note that locally defined components take precedence)‡If you ever wondered what the rules are for whether a name in JSX (so x
in <x>
) is a literal tag name (like h1
) or not (like Component
), they are as follows:
<a.b>
-> h(a.b)
), which means that the b
component is taken from object a
<a-b>
-> h('a-b')
)<a>
-> h('a')
)<A>
-> h(A)
), which means a component A
There is one special component: the layout. If it is defined, it’s used to wrap all content. A layout can be defined from within MDX using a default export:
export default function Layout({children}) {
return <main>{children}</main>;
}
All the things.
The layout can also be imported and then exported with an export … from
:
export {Layout as default} from './components.js'
The layout can also be passed as components.wrapper
(but a local one takes precedence).
You probably don’t need a provider. Passing components is typically fine. Providers often only add extra weight. Take for example this file:
# Hello world
Used like so:
import React from 'react'
import ReactDom from 'react-dom'
import {Heading, /* … */ Table} from './components/index.js'
import Post from './post.mdx' // Assumes an integration is used to compile MDX -> JS.
const components = {
h1: Heading.H1,
// …
table: Table
}
const root = ReactDom.createRoot(document.getElementById('root'))
root.render(<Post components={components} />)
That works, those components are used.
But when you’re nesting MDX files (importing them into each other) it can become cumbersome. Like so:
import License from './license.md' // Assumes an integration is used to compile MDX -> JS.
import Contributing from './docs/contributing.mdx'
# Hello world
<License components={props.components} />
---
<Contributing components={props.components} />
To solve this, a context can be used in React, Preact, and Vue. Context provides a way to pass data through the component tree without having to pass props down manually at every level. Set it up like so:
@mdx-js/react
, @mdx-js/preact
, or @mdx-js/vue
, depending on what framework you’re usingproviderImportSource
in ProcessorOptions
set to that package, so either '@mdx-js/react'
, '@mdx-js/preact'
, or '@mdx-js/vue'
MDXProvider
from that package. Use it to wrap your top-most MDX content component and pass it your components
instead:+import {MDXProvider} from '@mdx-js/react'
import React from 'react'
import ReactDom from 'react-dom'
import {Heading, /* … */ Table} from './components/index.js'
import Post from './post.mdx' // Assumes an integration is used to compile MDX -> JS.
const components = {
h1: Heading.H1,
// …
table: Table
}
const root = ReactDom.createRoot(document.getElementById('root'))
-root.render(<Post components={components} />)
+root.render(
+ <MDXProvider components={components}>
+ <Post />
+ </MDXProvider>
+)
Now you can remove the explicit and verbose component passing:
import License from './license.md' // Assumes an integration is used to compile MDX -> JS.
import Contributing from './docs/contributing.mdx'
# Hello world
-<License components={props.components} />
+<License />
---
-<Contributing components={props.components} />
+<Contributing />
When MDXProvider
s are nested, their components are merged. Take this example:
<>
<MDXProvider components={{h1: Component1, h2: Component2}}>
<MDXProvider components={{h2: Component3, h3: Component4}}>
<Content />
</MDXProvider>
</MDXProvider>
</>
…which results in h1
s using Component1
, h2
s using Component3
, and h3
s using Component4
.
To merge differently or not at all, pass a function to components
. It’s given the current context components
and what it returns will be used instead. In this example the current context components are discarded:
<>
<MDXProvider components={{h1: Component1, h2: Component2}}>
<MDXProvider
components={
function () {
return {h2: Component3, h3: Component4}
}
}
>
<Content />
</MDXProvider>
</MDXProvider>
</>
…which results in h2
s using Component3
and h3
s using Component4
. No component is used for h1
.
If you’re not nesting MDX files, or not nesting them often, don’t use providers: pass components explicitly.