0
# @mdx-js/react
1

2
@mdx-js/react provides React context and hooks for integrating MDX (Markdown for the component era) with React applications. It enables developers to customize how MDX elements are rendered by providing a context-based component mapping system.
3

4
## Package Information
5

6
- **Package Name**: @mdx-js/react
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript support)
9
- **Installation**: `npm install @mdx-js/react`
10

11
## Core Imports
12

13
```javascript
14
import { MDXProvider, useMDXComponents } from "@mdx-js/react";
15
```
16

17
CommonJS:
18

19
```javascript
20
const { MDXProvider, useMDXComponents } = require("@mdx-js/react");
21
```
22

23
## Basic Usage
24

25
```jsx
26
import { MDXProvider } from "@mdx-js/react";
27
import Post from "./post.mdx";
28

29
const components = {
30
  em(properties) {
31
    return <i {...properties} />;
32
  },
33
  h1(properties) {
34
    return <h1 style={{ color: "tomato" }} {...properties} />;
35
  },
36
};
37

38
function App() {
39
  return (
40
    <MDXProvider components={components}>
41
      <Post />
42
    </MDXProvider>
43
  );
44
}
45
```
46

47
## Capabilities
48

49
### Context Provider
50

51
The `MDXProvider` component creates a React context that supplies custom components to MDX content, enabling global customization of how MDX elements are rendered.
52

53
```typescript { .api }
54
/**
55
 * Provider for MDX context that supplies components to MDX content.
56
 * @param properties - Configuration object
57
 * @returns React element
58
 */
59
function MDXProvider(properties: Props): ReactElement;
60

61
interface Props {
62
  /** React children to wrap with MDX context */
63
  children?: ReactNode;
64
  /** Components object or merge function for customizing MDX elements */
65
  components?: MDXComponents | MergeComponents;
66
  /** Disable inheritance from parent MDX context (default: false) */
67
  disableParentContext?: boolean;
68
}
69
```
70

71
**Usage Examples:**
72

73
```jsx
74
// Basic component overrides
75
<MDXProvider
76
  components={{
77
    h1: (props) => <h1 style={{ color: "blue" }} {...props} />,
78
    em: (props) => <i {...props} />,
79
  }}
80
>
81
  <Content />
82
</MDXProvider>
83

84
// Nested providers with inheritance
85
<MDXProvider components={{ h1: BlueHeading }}>
86
  <MDXProvider components={{ h2: RedHeading }}>
87
    <Content /> {/* h1s are blue, h2s are red */}
88
  </MDXProvider>
89
</MDXProvider>
90

91
// Disabled inheritance (sandboxing)
92
<MDXProvider components={{ h1: BlueHeading }}>
93
  <MDXProvider disableParentContext components={{ h2: RedHeading }}>
94
    <Content /> {/* Only h2s are styled, h1s use default */}
95
  </MDXProvider>
96
</MDXProvider>
97
```
98

99
### Component Hook
100

101
The `useMDXComponents` hook retrieves and merges components from the MDX context, enabling custom component resolution within React components.
102

103
```typescript { .api }
104
/**
105
 * Get current components from the MDX context with optional additional components.
106
 * @param components - Optional additional components or merge function
107
 * @returns Merged components object from context and parameters
108
 */
109
function useMDXComponents(
110
  components?: MDXComponents | MergeComponents
111
): MDXComponents;
112
```
113

114
**Usage Examples:**
115

116
```jsx
117
import { useMDXComponents } from "@mdx-js/react";
118

119
function CustomContent() {
120
  // Get components from context
121
  const components = useMDXComponents();
122
  
123
  // Add/override specific components  
124
  const extendedComponents = useMDXComponents({
125
    p: (props) => <p className="custom-paragraph" {...props} />,
126
  });
127

128
  // Use function to merge with context
129
  const dynamicComponents = useMDXComponents((contextComponents) => ({
130
    ...contextComponents,
131
    strong: (props) => <b className="bold" {...props} />,
132
  }));
133

134
  return <div>/* Use components as needed */</div>;
135
}
136
```
137

138
### Component Merging Function
139

140
Custom merge function type for advanced component composition scenarios.
141

142
```typescript { .api }
143
/**
144
 * Custom merge function for combining components from context with additional components.
145
 * @param currentComponents - Current components from the MDX context
146
 * @returns Additional or modified components to merge
147
 */
148
type MergeComponents = (
149
  currentComponents: Readonly<MDXComponents>
150
) => MDXComponents;
151
```
152

153
**Usage Example:**
154

155
```jsx
156
<MDXProvider
157
  components={(contextComponents) => ({
158
    ...contextComponents,
159
    // Override existing h1 while preserving others
160
    h1: (props) => <h1 className="enhanced-heading" {...props} />,
161
    // Add new wrapper if not already present
162
    wrapper: contextComponents.wrapper || DefaultWrapper,
163
  })}
164
>
165
  <Content />
166
</MDXProvider>
167
```
168

169
## Types
170

171
```typescript { .api }
172
/** Components object mapping HTML element names to React components */
173
interface MDXComponents {
174
  [elementName: string]: ComponentType<any>;
175
  wrapper?: ComponentType<any>;
176
}
177

178
/** React node type for children */
179
type ReactNode = React.ReactNode;
180

181
/** React element type */
182
type ReactElement = React.ReactElement;
183

184
/** React component type */
185
type ComponentType<P = {}> = React.ComponentType<P>;
186
```
187

188
## Advanced Usage Patterns
189

190
### Wrapper Components
191

192
Special `wrapper` component for layout customization:
193

194
```jsx
195
const components = {
196
  wrapper: ({ children }) => (
197
    <div className="mdx-content">
198
      <header>MDX Content</header>
199
      {children}
200
      <footer>End of content</footer>
201
    </div>
202
  ),
203
};
204
```
205

206
### Conditional Component Mapping
207

208
```jsx
209
const components = {
210
  h1: (props) => {
211
    const level = props.level || 1;
212
    return level === 1 ? 
213
      <h1 className="title" {...props} /> : 
214
      <h1 className="subtitle" {...props} />;
215
  },
216
};
217
```
218

219
### Component Context Isolation
220

221
Use `disableParentContext` to create isolated component environments:
222

223
```jsx
224
// Parent context ignored, only local components used
225
<MDXProvider disableParentContext components={isolatedComponents}>
226
  <Content />
227
</MDXProvider>
228
```