Have ideas to improve npm?Join in the discussion! »


1.4.0 • Public • Published

React Styleguide Generator

CircleCI npm Join the chat at https://gitter.im/pocotan001/react-styleguide-generator

Easily generate a good-looking styleguide by adding some documentation to your React project.

Demo using the React-Bootstrap.


npm install react-styleguide-generator

Which requires React 15.x.x or newer. To install it npm install react.

Quick Start

NOTE: By default Babel's static keyword is disabled. You can turn them on individually by passing stage 0 as a babelrc or options.babelConfig.

Documenting your React components

Create file for the styleguide, and then add some documentation to a static field named styleguide. You can use the ES6 syntax by Babel.

import React from 'react'
import Button from './Button'
export default class extends React.Component {
  static styleguide = {
    index: '1.1',
    category: 'Elements',
    title: 'Button',
    description: 'You can use **Markdown** within this `description` field.',
    code: `<Button size='small|large' onClick={Function}>Cool Button</Button>`,
    className: 'apply the css class'
  onClick () {
  render () {
    return (
      <Button size='large' onClick={this.onClick}>Cool Button</Button>
  • index: Reference to the element's position in the styleguide (optional)
  • category: Components category name
  • title: Components title
  • description: Components description (optional)
  • code: Code example (optional). Not specifying this will not auto-generate an example.
  • className: CSS class name (optional)

Additional examples in tabs (optional) Demo

You can optionally use tabs to segment out examples for a component:

import React from 'react'
import Button from './Button'
export default class extends React.Component {
  static styleguide = {
    // Component to use for generating additional examples
    exampleComponent: Button,
    // Array of additional example tabs
    examples: [{
      tabTitle: 'Default',
      props: {
        children: 'Default'
    }, {
      tabTitle: 'Primary',
      props: {
        kind: 'primary',
        children: 'Primary',
        onClick () {
          alert('o hay!')
  • exampleComponent: ReactElement to use to generate the examples.
  • examples: Array of examples, which generates additional tabs of example components and sample code
  • examples[].tabTitle: Title of example tab
  • examples[].props: Properties to assign to the rendered example component
  • examples[].props.children: (optional) Child elements to assign to the example component
  • examples[].code: (optional) Code example. Omitting this will attempt to auto-generate a code example using the examples[].props

Additional examples via doc comment (optional) Demo

Doc comment support example is:

 * Substitute this description for `styleguide.description`.
export default class extends Component {
  // required for prop documentation
  static displayName = 'ExampleButton'
  static styleguide = {
  // Document the props via react-docgen
  static propTypes = {
     * Block level
    block: React.PropTypes.bool,
     * Style types
    kind: React.PropTypes.oneOf(['default', 'primary', 'success', 'info'])
  render () {
    return <Button block kind='primary'>Cool Button</Button>

If necessary, visit react-styleguide-generator/example to see more complete examples for the documenting syntax.

Generating the documentation

Command line tool

A common usage example is below.

# The default output to `styleguide` directory 
rsg 'example/**/*.js'

Type rsg -h or rsg --help to get all the available options.

Usage: rsg [input] [options]

  -o, --output     Output directory            ['styleguide']
  -t, --title      Used as a page title        ['Style Guide']
  -r, --root       Set the root path           ['.']
  -f, --files      Inject references to files  ['']
  -c, --config     Use the config file         ['styleguide.json']
  -p, --pushstate  Enable HTML5 pushState      [false]
  -v, --verbose    Verbose output              [false]
  -w, --watch      Watch mode using `browserifyConfig`

  rsg 'example/**/*.js' -t 'Great Style Guide' -f 'a.css, a.js' -v

  # Necessary to use a config file if you want to enable react-docgen
  rsg 'example/**/*.js' -c 'styleguide.json' -v


var gulp = require('gulp')
var RSG = require('react-styleguide-generator')
gulp.task('styleguide', function (done) {
  var rsg = RSG('example/**/*.js', {
    output: 'path/to/dir',
    files: ['a.css', 'a.js']
  rsg.generate(function (err) {
    if (err) {


var RSG = require('react-styleguide-generator')
grunt.registerTask('rsg', 'React style guide', function () {
  var done = this.async()
  try {
    var conf = grunt.config.get('rsg')
    RSG(conf.input, {
      config: conf.configFile,
      watch: false,
      verbose: true
    }).generate(function (err) {
      if (err) {
          grunt.log.error('Error: ' + err + ' ' + err.stack())
          return done(false)
      grunt.log.ok('react styleguide generation complete')
  } catch (e) {
    grunt.log.error('Error: ' + e + ' ' + e.stack)


RSG(input, [options])

Returns a new RSG instance.


Type: String

Refers to glob syntax or it can be a direct file path.



Type: String
Default: 'styleguide'

Output directory path.


Type: String
Default: 'Style Guide'

Used as a page title and in the page header.


Type: Array Default: input

An array of glob-able file/paths for react-docgen to parse. If not specified, will default the value to input.


Type: String
Default: '.'

Set the root path. For example, if the styleguide is hosted at http://example.com/styleguide the options.root should be styleguide.


Type: Array
Default: null

Inject references to files. A usage example is:

  files: [

Check for the existence of the files and only copy the files if it exists.

├─ a.css
├─ a.js
└─ icon.svg

Inject file references into index.html if the files with the extension .css or .js.

<!doctype html>
    <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css">
    <link rel="stylesheet" href="files/a.css">
    <script src="files/a.js"></script> 

Type: String|Object
Default: styleguide.json

The entire range of RSG API options is allowed. Usage example.

An object can be passed instead of a filename that contains the RSG API options.


Type: String
Default: false

Enable HTML5 pushState. When this option is enabled, styleguide will use history API.


Type: Object
Default: null

A usage example is below. See the babel docs for the complete list.

  babelConfig: {
    stage: 0

Type: Object
Default: { standalone: 'Contents', debug: true }

A usage example is below. See the browserify docs for the complete list.

  extensions: ['', '.js', '.jsx']


Type: String Default: false

Enables watchify for when the input files change, speeding up rebuild time.


Generate the files and their dependencies into a styleguide output.


Get the demo running locally:

git clone git@github.com:pocotan001/react-styleguide-generator.git
cd react-styleguide-generator/example/
npm install
npm start

Visit http://localhost:3000/ in your browser.


Error: No suitable component definition found.

Make sure your component contains displayName and render().


npm i react-styleguide-generator

DownloadsWeekly Downloads






Last publish


  • avatar
  • avatar