React Scenes

React Scenes is a simple way to create/test your react components inside your app.



We tried lots of tools to simplify our in-house react component creation process, but somehow nothing feel right. React Scenes is more simple, easy to use and flexible. (plus built-in support for styled-components)


npm install react-scenes --save

Custom Installation

install cli for react-scenes

npm install react-scenes-cli -g

then on your app root folder

setReactScenes -l "My Scenes"

this will create an entire seperate app with CRA and all dependencies.

setReactScenes -l "My Scenes" --bare
this will only generate template files.

PS: both will install react-scenes from npm.



Libraries is just a react component that uses Scenes, you can point any route to any library just like normal pages.

import { Scenes } from "react-scenes";
import scenes from "./index";

class Library extends Component {
  render() {
    return (
        title="? My Scenes"
        config={ {
          panel: {
            position: "right"
        } }
        scenes={Object.keys(scenes).map(key => scenes[key])}

export default Library;

title string

Library Title.

scenes array


config object

panel object

Default value of panel position.

panel: {position: : "right"} // left, right, top, bottom

ui boolean

Default value of UI Visibility. ui: true

sizer boolean

Default value of Viewport Sizer Visibility. sizer: true

caching boolean

Default value of State Recording. caching: true

device string|object

Default value or Viewport Device or Size.

device: "iphonex"

Other pre-defined devices: iphonex, iphone8p, iphone8, iphonese,ipadpro, ipadprol, ipad, ipadl, pixel2

PS: "l" for landscape


device: {width: 320, height: 320, unit: "px"}

frame object

We use react-frame-component for wrapping your components, you can set its options in here.

frame : {
  initialContent:`<!DOCTYPE html>
      @import url("");
      body {
        font-family: "sofia-pro";
        font-weight: 400;

      strong {
        font-weight: 600;
    <div id="frame"></div>
  mountTarget: "#frame"

plus on some rare cases you may want to inject parent page's stylesheets so just add below to frame property.

injectGlobalStylesheets: true

and also if you use styled-components add below to frame property to inject component style to iframe.

injectStyledComponentsStylesheets: true

actions array

check for more: custom actions

panels array

check for more: custom panels

devices array

check for more: custom devices


Example scene

import { controllers } from "react-scenes";

export default {
  title: "Hello",
  target: Bar,
  controllers: [
      key: "title",
      title: "My title",
      controller: controllers.text("hello")
  events: ["onClick"],
  options: {
    centered: true,
    theme: "light" // light, dark, white, black
  docs: `## Bar
  **Hello World**

title string required

Title of your component.
You can also make titles nested like Buttons>Normal.

target React Component or function required

Your Component. You can either give your component directly or you can pass a functions.

target: ({props,state,setState}) => {
  return (
      <Button {...props}>{props.title}</Button>

controllers array

All the controllers your component need. They will be passed to your component as their props.

events array

Events you want to track.

options object

Two options are available. theme and centered (makes component centered in viewport with flexbox).

docs string

Component documentation or notes.

displayName string

Sometimes displayName could be different then what it should be, you can use this if your component name is wrong in Code Panel.

stylesheet string

Use this to pass any css to components iframe.

styleClassNames array

Use this if you import your css into your js file (webpack).

Import your css like,

import style from "./style.css"
style.className = "my-style"

then add all classNames you need to this property.

Built-in Features

Scenes has ;

  • Actions for global manipulation
  • Panels for component manipulation


We provide 4 actions; UI Visibility Toggle, State Recording Toggle, Viewport Sizer, Panel Position Toggle

You can add custom actions into config as actions check for more: custom actions

Toggle UI Visibility ?

Toggles ui elements from scenes. (scene picker, panels etc.)

State Recording ⏸

When state recording is on all controllers data will be cached on local storge for easy testing.

Viewport Sizing ?

You can change viewport to known devices and you can enter custom width and height.

PS: check for more: custom devices

Panel Positioning ➡️

You can change your panel position on the fly or you can set your default panel postion inside your library config.


We provide 4 panels;
You can add custom panels into config as panel check for more: custom panels

Every panel can has its own specific actions check for more: custom panel actions

Controllers ?

Conrollers are your main tools to alter your component without direct input.

We provide 10 default controllers; text,textarea,select,boolean,integer,float,range,object,array,color


controllers.text("Hello World")


controllers.textarea("Hello \n World")

select"primary", ["primary", "destructive"])

or you can add as key,value"primary", [
  {key:"Primary, value:"primary"},
  {key:"Positive, value:"positive"}

controllers.boolean(true, true) > if you set second argument it will include null to controller cycle.












controllers.color("#000","hex" // hex, rgb, rgba)

Docs ?

Docs are can be component documentation or any other notes. (markdown supported).

Events ?

Track your components events, just add event props to your scenes as an array.

Code ?

This converts your components code to string for easy sharing.


Custom Actions

We exposed props, state, store, setState so you can access to alter anything you like.

PS: from props you can react setScene and setConfig.
PS2: you can use store to set and get things from local storage.

      _id: "say-hi",
      icon: ({ props, store }) => {
        return props.config.areWeMet ? "☺️" : "?"
      onClick: ({ props, state, store, setState }) => {
        props.setConfig({ weMet: !props.config.areWeMet });

Custom Panels

We exposed props, state, store, setState so you can access to alter anything you like.

PS: from props you can react options, setScene, setOptions and setConfig.
PS2: you can use store to set and get things from local storage.

        _id: "my-apples",
        component: MyApples,
        active: ({ state }) => == "my-panel",
        icon: "?",
        actions: [
            _id: "toggle-apple-color",
            icon: ({props})=> == "green" ? "?" : "?",
            active: ({ props }) => == "green",
            onClick: ({ props }) => {
                centered: == "green" ? "red" : "green"

Custom Controllers

Example: myApp/.../myCustomController.js

import React, { Component } from "react";

export default (initialValue, foo, bar) => {
  return {
    type: "customController",
    process: val => val,
    input: (value, set, title, state, setState) => {
      return (
        <div className="custom-controller">
            onChange={e => set(}
            onFocus={e => setState({focused: true})}
            onBlur={e => setState({focused: false})}
          {focused ? "Focused" : "Not Focused"}

There is 4 props you can use;

  • type string is just and identifier.

  • initialValue anything is the initial value of the input.

  • process function can be use to alter the input value.

  • input function has value, set, title, state, setState to update your data and state of your controller.


Example: someScene.js

import customController from "../myCustomController";

export default {
  title: "Hello",
  target: Bar,
  controllers: [
      key: "data",
      title: "My Data",
      controller: customController("hello", "foo", "bar")

Custom Devices

to add custom device sizes, inject it to Scenes like below.

    iphonex: {
      title: "iPhone X",
      width: 375,
      height: 812
    iphoneflex: {
      title: "iPhone Flex",
      width: "375px",
      height: "100%",
      unit: ""