https://github.com/alsiola/react-doc-props
Create documented React components
https://github.com/alsiola/react-doc-props
documentation-generator prop-types react
Last synced: 2 months ago
JSON representation
Create documented React components
- Host: GitHub
- URL: https://github.com/alsiola/react-doc-props
- Owner: alsiola
- License: mit
- Created: 2017-04-22T11:17:51.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2018-04-30T21:27:10.000Z (over 7 years ago)
- Last Synced: 2025-10-04T07:38:59.536Z (3 months ago)
- Topics: documentation-generator, prop-types, react
- Language: JavaScript
- Homepage: https://alsiola.github.io/react-doc-props/
- Size: 1.9 MB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
[](https://travis-ci.org/alsiola/react-doc-props)
[](https://coveralls.io/github/alsiola/react-doc-props?branch=master)
# react-doc-props
react-doc-props is a package that allows you to write comprehensive in-file documentation of React components. This documentation will then generate the correct propTypes and defaultProps for your component.
## Installation
Install with your package manager of choice:
````
npm install --save react-doc-props
````
## Usage
The basic react-doc-props documentation object looks like this.
````
export const documentation = {
name: 'ComponentName',
description: 'A description of the component',
props: {
// a object of props keyed by propName - see below
}
};
````
This documentation object is then converted to the appropriate propTypes and defaultProps objects, and applied to the component with the `setComponentProps` function:
````
import { setComponentProps } from 'react-doc-props';
setComponentProps(documentation, Component);
````
### Simple Prop Types
The `documentation.props` object is constructed using the propTypes exported by react-prop-docs:
````
import { string } from 'react-doc-props';
````
Which are then used in the documentation object:
````
const documentation = {
name: 'ComponentName',
description: 'A description of the component',
props: {
title: {
type: string,
description: 'The title of the component',
default: 'A default title'
}
}
};
````
If a prop is required then, as with the React PropTypes, just add `.isRequired`:
````
const documentation = {
name: 'ComponentName',
description: 'A description of the component',
props: {
title: {
type: string.isRequired,
description: 'The title of the component',
default: 'A default title'
}
}
};
````
The simple propTypes are all used in the same way, and all of the React PropTypes are available:
````
import { string, number, boolean, object, func, array, symbol, element, node, any } from 'react-doc-props';
````
### Shape
A shape propType is created by using the `shape` function from `react-doc-props`. The shape required is passed as an argument - this argument should be an object with the same structure as the `documentation.props` object:
````
import { shape, string, number } from 'react-doc-props';
const documentation = {
name: 'ComponentName',
description: 'A description of the component',
props: {
user: {
type: shape({
name: {
type: string,
description: 'The users name'
},
age: {
type: number,
description: 'The users age in years'
}
}),
description: 'The current user',
default: {
name: 'No name set',
age: -1
}
}
}
};
````
If a shape is required, then `shape.isRequired()` can be used:
````
import { shape, string, number } from 'react-doc-props';
const documentation = {
name: 'ComponentName',
description: 'A description of the component',
props: {
user: {
type: shape.isRequired({
name: {
type: string,
description: 'The users name'
},
age: {
type: number,
description: 'The users age in years'
}
}),
description: 'The current user'
}
}
};
````
### InstanceOf
An instanceOf propType is created with the `instanceOf` function from `react-doc-props`. It takes two arguments: the class the prop must be an instance of, and optionally a display name for that class.
````
import { instanceOf } from 'react-doc-props';
const documentation = {
name: 'ComponentName',
description: 'A description of the component',
props: {
loginMsg: {
type: instanceOf(Message, 'Message'),
description: 'A message about login.'
}
}
};
````
If the prop is required, then use the `instanceOf.isRequired()` function.
### ArrayOf and ObjectOf
ArrayOf and ObjectOf work in the same way, using `arrayOf` and `objectOf` respectively:
````
import { arrayOf, objectOf, string } from 'react-doc-props';
const documentation = {
name: 'ComponentName',
description: 'A description of the component',
props: {
names: {
type: arrayOf(string),
description: 'An array of user names.'
},
languages: {
type: objectOf(string),
description: 'The preferred language of a user keyed by user name'
}
}
};
````
Again, substitute with `arrayOf.isRequired` or `objectOf.isRequired` for required props.
### OneOf
OneOf prop types can be defined using the `oneOf` and `oneOf.isRequired` functions, with a single argument - an array of the possible values.
````
import { oneOf } from 'react-prop-types';
const documentation = {
name: 'ComponentName',
description: 'A description of the component',
props: {
openDirection: {
type: oneOf( ['up', 'down', 'left', 'right'] ),
description: 'An array of user names.'
}
}
};
````
### OneOfType
OneOfType prop types can be defined with the `oneOfType` and `oneOfType.isRequired` functions. The single argument is an array of possible types.
````
import { oneOfType, string, number } from 'react-prop-types';
const documentation = {
name: 'ComponentName',
description: 'A description of the component',
props: {
time: {
type: oneOfType([ string, number ]),
description: 'The current time as a string or timestamp.'
}
}
};
````
### Custom Validator Functions
The use of custom validator functions is supported with the `custom` function, passing the validator function as an argument:
````
import { custom } from 'react-prop-types';
const singleCharStringValidator = (props, propName, component) => {
if (!props[propName] ||typeof props[propName] !== 'string' || props[propName].length !== 1) {
return new Error(`Invalid prop ${propName} supplied to ${component}.`);
}
}
const documentation = {
name: 'ComponentName',
description: 'A description of the component',
props: {
initial: {
type: custom(singleCharStringValidator)
description: 'A single letter initial.'
}
}
};
````