0
# Parser Options
1

2
Comprehensive configuration options for customizing parsing behavior, filtering properties, and controlling output format.
3

4
## Capabilities
5

6
### ParserOptions Interface
7

8
Main configuration interface for customizing parser behavior.
9

10
```typescript { .api }
11
/**
12
 * Configuration options for the parser
13
 */
14
interface ParserOptions {
15
  /** Filter function or configuration for properties */
16
  propFilter?: StaticPropFilter | PropFilter;
17
  /** Custom component name resolver function */
18
  componentNameResolver?: ComponentNameResolver;
19
  /** Extract literal values from string enums */  
20
  shouldExtractLiteralValuesFromEnum?: boolean;
21
  /** Remove " | undefined" from optional types display */
22
  shouldRemoveUndefinedFromOptional?: boolean;
23
  /** Extract all union type values as enum format */
24
  shouldExtractValuesFromUnion?: boolean;
25
  /** Sort union members alphabetically */
26
  shouldSortUnions?: boolean;
27
  /** Skip children prop when it has no documentation */
28
  skipChildrenPropWithoutDoc?: boolean;
29
  /** Save default prop values as strings instead of parsed values */
30
  savePropValueAsString?: boolean;
31
  /** Include JSDoc tag mappings in prop documentation */
32
  shouldIncludePropTagMap?: boolean;
33
  /** Include TypeScript expression symbols in output */
34
  shouldIncludeExpression?: boolean;
35
  /** Custom component type names to recognize */
36
  customComponentTypes?: string[];
37
}
38
```
39

40
### Property Filtering
41

42
Control which properties are included in the documentation output.
43

44
```typescript { .api }
45
/**
46
 * Function type for filtering properties
47
 * @param prop - Property information
48
 * @param component - Component information
49
 * @returns true to include prop, false to exclude
50
 */
51
type PropFilter = (prop: PropItem, component: Component) => boolean;
52

53
/**
54
 * Static filter configuration for properties
55
 */
56
interface StaticPropFilter {
57
  /** Property names to skip (string or array) */
58
  skipPropsWithName?: string[] | string;
59
  /** Skip properties without JSDoc documentation */
60
  skipPropsWithoutDoc?: boolean;
61
}
62
```
63

64
**Usage Examples:**
65

66
```typescript
67
import { parse } from "react-docgen-typescript";
68

69
// Static filtering
70
const docsWithStaticFilter = parse("./src/Button.tsx", {
71
  propFilter: {
72
    skipPropsWithName: ['className', 'style', 'key', 'ref'],
73
    skipPropsWithoutDoc: true
74
  }
75
});
76

77
// Function-based filtering
78
const docsWithFunctionFilter = parse("./src/Button.tsx", {
79
  propFilter: (prop, component) => {
80
    // Skip props from node_modules
81
    if (prop.declarations?.some(decl => decl.fileName.includes('node_modules'))) {
82
      return false;
83
    }
84
    
85
    // Skip HTML attributes for certain components
86
    if (component.name === 'Button' && ['onClick', 'onFocus', 'onBlur'].includes(prop.name)) {
87
      return false;
88
    }
89
    
90
    return true;
91
  }
92
});
93
```
94

95
### Component Name Resolution
96

97
Customize how component names are determined.
98

99
```typescript { .api }
100
/**
101
 * Function type for resolving component names
102
 * @param exp - TypeScript symbol for the component
103
 * @param source - Source file containing the component
104
 * @returns Component name, or undefined/null/false to use default logic
105
 */
106
type ComponentNameResolver = (
107
  exp: ts.Symbol,
108
  source: ts.SourceFile
109
) => string | undefined | null | false;
110
```
111

112
**Usage Examples:**
113

114
```typescript
115
import { parse } from "react-docgen-typescript";
116

117
const docs = parse("./src/StyledButton.tsx", {
118
  componentNameResolver: (exp, source) => {
119
    // Handle styled-components
120
    if (exp.getName() === "StyledComponentClass") {
121
      return "StyledButton";
122
    }
123
    
124
    // Handle default exports  
125
    if (exp.getName() === "default") {
126
      const fileName = source.fileName.split('/').pop()?.replace('.tsx', '');
127
      return fileName;
128
    }
129
    
130
    // Use default logic
131
    return undefined;
132
  }
133
});
134
```
135

136
### Type Extraction Options
137

138
Control how TypeScript types are processed and displayed.
139

140
```typescript { .api }
141
// Extract enum literal values
142
shouldExtractLiteralValuesFromEnum?: boolean;
143

144
// Extract union type values  
145
shouldExtractValuesFromUnion?: boolean;
146

147
// Sort union members
148
shouldSortUnions?: boolean;
149

150
// Remove undefined from optional types
151
shouldRemoveUndefinedFromOptional?: boolean;
152
```
153

154
**Usage Examples:**
155

156
```typescript
157
import { parse } from "react-docgen-typescript";
158

159
// Enhanced type extraction
160
const docs = parse("./src/Button.tsx", {
161
  shouldExtractLiteralValuesFromEnum: true,
162
  shouldExtractValuesFromUnion: true,
163
  shouldSortUnions: true,
164
  shouldRemoveUndefinedFromOptional: true
165
});
166

167
// Results in detailed enum information:
168
// type: { name: "enum", value: [{ value: '"danger"' }, { value: '"primary"' }, { value: '"secondary"' }] }
169
// instead of: { name: '"primary" | "secondary" | "danger"' }
170
```
171

172
### Default Value Handling
173

174
Control how default property values are captured and formatted.
175

176
```typescript { .api }
177
// Save default values as strings
178
savePropValueAsString?: boolean;
179
```
180

181
**Usage Examples:**
182

183
```typescript
184
import { parse } from "react-docgen-typescript";
185

186
// String default values
187
const docsWithStringDefaults = parse("./src/Counter.tsx", {
188
  savePropValueAsString: true
189
});
190
// Result: { defaultValue: { value: "123" } }
191

192
// Parsed default values (default behavior)
193
const docsWithParsedDefaults = parse("./src/Counter.tsx", {
194
  savePropValueAsString: false
195
});
196
// Result: { defaultValue: { value: 123 } }
197
```
198

199
### Documentation Enhancement Options
200

201
Control additional metadata inclusion in the output.
202

203
```typescript { .api }
204
// Include JSDoc tag mappings
205
shouldIncludePropTagMap?: boolean;
206

207
// Include TypeScript expressions  
208
shouldIncludeExpression?: boolean;
209

210
// Skip children prop without docs
211
skipChildrenPropWithoutDoc?: boolean;
212
```
213

214
**Usage Examples:**
215

216
```typescript
217
import { parse } from "react-docgen-typescript";
218

219
const enhancedDocs = parse("./src/Button.tsx", {
220
  shouldIncludePropTagMap: true,
221
  shouldIncludeExpression: true,
222
  skipChildrenPropWithoutDoc: false
223
});
224

225
// Includes additional metadata:
226
// - JSDoc tags in prop.tags
227
// - TypeScript symbols in componentDoc.expression
228
// - children prop even without documentation
229
```
230

231
### Custom Component Types
232

233
Extend component recognition beyond default React patterns.
234

235
```typescript { .api }
236
// Custom component type names
237
customComponentTypes?: string[];
238
```
239

240
**Usage Examples:**
241

242
```typescript
243
import { parse } from "react-docgen-typescript";
244

245
const docs = parse("./src/CustomComponent.tsx", {
246
  customComponentTypes: [
247
    'MyCustomComponent',
248
    'SpecialWrapper',
249
    'ThirdPartyComponent'
250
  ]
251
});
252

253
// Recognizes components with these type names as valid React components
254
```
255

256
## Complete Configuration Example
257

258
```typescript
259
import { withDefaultConfig } from "react-docgen-typescript";
260

261
const parser = withDefaultConfig({
262
  propFilter: {
263
    skipPropsWithName: ['className', 'style'],
264
    skipPropsWithoutDoc: true
265
  },
266
  componentNameResolver: (exp, source) => {
267
    if (exp.getName() === "StyledComponentClass") {
268
      return source.fileName.split('/').pop()?.replace('.tsx', '') || 'Component';
269
    }
270
    return undefined;
271
  },
272
  shouldExtractLiteralValuesFromEnum: true,
273
  shouldExtractValuesFromUnion: true,
274
  shouldSortUnions: true,
275
  shouldRemoveUndefinedFromOptional: true,
276
  skipChildrenPropWithoutDoc: true,
277
  savePropValueAsString: true,
278
  shouldIncludePropTagMap: true,
279
  shouldIncludeExpression: false,
280
  customComponentTypes: ['StyledComponent', 'MyCustomWrapper']
281
});
282

283
const docs = parser.parse("./src/components/*.tsx");
284
```
285

286
## Default Values
287

288
```typescript { .api }
289
/**
290
 * Default parser options (empty object)
291
 */
292
const defaultParserOpts: ParserOptions;
293
```
294

295
When no options are provided, the parser uses sensible defaults:
296

297
- No property filtering (all props included)
298
- Default component name resolution
299
- Basic type extraction without enum/union processing
300
- Include children prop regardless of documentation
301
- Parse default values to their actual types
302
- Minimal metadata inclusion