Skip to content
This repository has been archived by the owner on Aug 10, 2018. It is now read-only.


Folders and files

Last commit message
Last commit date

Latest commit


Repository files navigation

React Styleguide Generator

CircleCI npm Join the chat at

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


const gulp = require('gulp')
const rsg = require('react-styleguide-generator').rsg

gulp.task('styleguide', function (done) {
  rsg('example/**/*.js', {
    output: 'path/to/dir',
    files: ['a.css', 'a.js']
    .then(() => done())
    .catch(err => {


const rsg = require('react-styleguide-generator').rsg

grunt.registerTask('rsg', 'React style guide', function () {
  const done = this.async()

  try {
    const conf = grunt.config.get('rsg')

    rsg(conf.input, {
      config: conf.configFile,
      watch: false,
      verbose: true
      .then(() => {
        grunt.log.ok('react styleguide generation complete')
      .catch(err => {
        grunt.log.error('Error: ' + err + ' ' + err.stack())
  } 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 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>
  <head><link rel="stylesheet" href="//">
    <link rel="stylesheet" href="files/a.css">
  <body><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
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().