0
# Component Interface
1

2
React component wrapper providing convenient JSX integration with markdown content and configuration options.
3

4
## Capabilities
5

6
### Markdown Component
7

8
High-level React component that accepts markdown content as children and renders it as JSX with optional configuration.
9

10
```typescript { .api }
11
/**
12
 * React component that renders markdown content as JSX
13
 * Accepts markdown string as children and optional configuration
14
 */
15
const Markdown: React.FC<MarkdownComponentProps>;
16

17
interface MarkdownComponentProps extends Omit<React.HTMLAttributes<Element>, 'children'> {
18
  /** Markdown content as string */
19
  children: string;
20
  /** Configuration options for parsing and rendering */
21
  options?: MarkdownToJSX.Options;
22
}
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import Markdown from "markdown-to-jsx";
29
import React from "react";
30

31
// Basic usage
32
function BasicExample() {
33
  return (
34
    <Markdown>
35
      # Welcome
36
      
37
      This is **markdown** content!
38
    </Markdown>
39
  );
40
}
41

42
// With options
43
function WithOptions() {
44
  return (
45
    <Markdown
46
      options={{
47
        overrides: {
48
          h1: { props: { className: "main-title" } },
49
          p: { props: { className: "paragraph" } }
50
        }
51
      }}
52
    >
53
      # Custom Styled Title
54
      
55
      This paragraph will have custom styling.
56
    </Markdown>
57
  );
58
}
59

60
// With additional HTML props
61
function WithProps() {
62
  return (
63
    <Markdown 
64
      className="markdown-container"
65
      id="content"
66
      data-testid="markdown-content"
67
    >
68
      # Content
69
      
70
      The wrapper element will receive these props.
71
    </Markdown>
72
  );
73
}
74

75
// Dynamic content
76
function DynamicContent({ content }: { content: string }) {
77
  return (
78
    <Markdown options={{ forceBlock: true }}>
79
      {content}
80
    </Markdown>
81
  );
82
}
83
```
84

85
### Props Merging
86

87
The component automatically merges additional props with the wrapper element, allowing for full HTML attribute support.
88

89
```typescript
90
// Props are passed through to the wrapper element
91
<Markdown 
92
  className="custom-class"
93
  style={{ padding: '1rem' }}
94
  onClick={handleClick}
95
  data-markdown="true"
96
>
97
  # Clickable Content
98
</Markdown>
99

100
// Results in wrapper element with all props applied
101
```
102

103
### Wrapper Element Behavior
104

105
The component intelligently chooses wrapper elements based on content and configuration:
106

107
- **Inline content**: Wrapped in `<span>` by default
108
- **Block content**: Wrapped in `<div>` by default  
109
- **Multiple elements**: Always wrapped in container
110
- **Single element**: May be unwrapped unless `forceWrapper: true`
111
- **Custom wrapper**: Use `options.wrapper` to specify element type
112
- **No wrapper**: Use `options.wrapper: null` to return array of elements
113

114
**Usage Examples:**
115

116
```typescript
117
// Inline content (wrapped in span)
118
<Markdown>Just some *italic* text</Markdown>
119
// Renders: <span>Just some <em>italic</em> text</span>
120

121
// Block content (wrapped in div)
122
<Markdown>
123
  # Title
124
  
125
  Paragraph content
126
</Markdown>
127
// Renders: <div><h1>Title</h1><p>Paragraph content</p></div>
128

129
// Custom wrapper
130
<Markdown options={{ wrapper: "article" }}>
131
  # Article Title
132
  Content here
133
</Markdown>
134
// Renders: <article>...</article>
135

136
// No wrapper (returns array)
137
<Markdown options={{ wrapper: null }}>
138
  # Title
139
  Content
140
</Markdown>
141
// Renders: [<h1>Title</h1>, <p>Content</p>]
142

143
// Force wrapper for single elements
144
<Markdown options={{ forceWrapper: true }}>
145
  Just a single paragraph
146
</Markdown>
147
// Renders: <span><p>Just a single paragraph</p></span>
148
```
149

150
### Error Handling
151

152
The component provides user-friendly error handling for invalid inputs and malformed markdown.
153

154
```typescript
155
// Component validates input type
156
<Markdown>{123}</Markdown> // Logs error in development
157

158
// Handles empty content gracefully
159
<Markdown>{""}</Markdown> // Renders empty span
160

161
// Handles undefined content
162
<Markdown>{undefined}</Markdown> // Treats as empty string
163
```
164

165
### Development Mode Features
166

167
Additional validation and warnings in development mode for better developer experience.
168

169
```typescript
170
// Development warnings for common mistakes
171
<Markdown>{123}</Markdown> 
172
// Console warning: "markdown-to-jsx: component only accepts string children"
173

174
<Markdown options={{ overrides: "invalid" }}>Content</Markdown>
175
// Console error: "options.overrides must be an object literal"
176
```
177

178
### TypeScript Integration
179

180
Full TypeScript support with proper type checking for props and options.
181

182
```typescript
183
import Markdown from "markdown-to-jsx";
184

185
// TypeScript ensures correct prop types
186
function TypedComponent({ content }: { content: string }) {
187
  return (
188
    <Markdown 
189
      options={{
190
        overrides: {
191
          // TypeScript validates override structure
192
          h1: { 
193
            component: "h2", // Valid
194
            props: { className: "title" } // Valid
195
          },
196
          p: CustomParagraph // Valid React component
197
        }
198
      }}
199
    >
200
      {content}
201
    </Markdown>
202
  );
203
}
204

205
// Custom component with proper typing
206
const CustomParagraph: React.FC<React.PropsWithChildren<{}>> = ({ children }) => (
207
  <p className="custom-paragraph">{children}</p>
208
);
209
```