React Playground Styled
This is a playground styled with styled-components. It enables you to create custom playgrounds to meet your exact needs. It allows context based themes from styled-components to penetrate into playgrounds so you can create themable living component guides.
It is designed to be as small as possible so it does not break the flow of your docs. It is responsive and supports hot loading so it can be used to test components performance on mobile while you develop:
Install
Bash:
npm install --save react-playground-styledJavaScript:
import ReactPlaygroundStyled from 'react-playground-styled'Use
The viewer (left) will evalute the last expression in the editor (right) and if it is a React element it will be rendered in the viewer:
<div className="Edit"> <button>Hello</button></div>I appologise if this is a bit meta, but I am going to be using the playground to document itself hence you may see a playground within a playground for most examples. You will see the inner playground has a different style to the outer one (I will show you how to achieve this later). The code for the playground is set by putting it in the defaultValue prop:
xxxxxxxxxx<button>Hello</button>// import ReactPlaygroundStyled from 'react-playground-styled'<ReactPlaygroundStyled defaultValue={'<button>Hello</button>'}/>You pass in components, functions and variables as an Object (map) in the scope prop (often these will be imported from the package you are documenting). Remember it accepts an Object (not a single component) where each value is a function, a value or a component.
xxxxxxxxxx<HelloWorld onClick={onClick} />xxxxxxxxxxconst onClick = () => alert('hello')const HelloWorld = () => ( <strong onClick={onClick}>Hello World!</strong>);<ReactPlaygroundStyled defaultValue={'<HelloWorld onClick={onClick} />'} scope={{onClick, HelloWorld}}/>NOTE: A semicolon is needed on the last line before the JSX to force it to be evaluated. As a rule of thumb make sure the last non-whitespace character before the evaluated JSX is either a semicolon ';' or a closing curly '}' (failure to include this semi will give an error):
One of the goals of this playground is to be lightweight, for this reason we use Bublé rather than Babel. This makes bundle downloads on the browser a few megabytes smaller:
Editor Settings
Another goal is to use minimal screen space to document a component. Because horizontal space is at such a high premium I have taken the unusual decision to use a proportional font by default. I found this to be less evil than all the line wrapping I encountered with monospace fonts. You can change the font with the font property:
xxxxxxxxxx<button>Hello</button>xxxxxxxxxx<ReactPlaygroundStyled font={'consolas, monospace'} defaultValue={'<button>Hello</button>'}/>You can load fonts from Google Fonts and change the editorFontSize:
xxxxxxxxxx<button>Hello</button>xxxxxxxxxx<ReactPlaygroundStyled editorFontSize="18px" googleFont="Indie Flower" font={'Indie Flower, monospace'} defaultValue={'<button>Hello</button>'}/>loadTheme to loads CodeMirror CSS themes from a CDN. There is a list of themes in the textarea below. Try pasting them into the loadTheme prop on the right:
xxxxxxxxxxconst a = 1;let b = [1,2,3];<textarea readOnly value={themeNames.join('\n')} rows={15}/>xxxxxxxxxx<ReactPlaygroundStyled scope={{ themeNames }} loadTheme="monokai" defaultValue={`const a = 1;let b = [1,2,3];<textarea readOnly value={themeNames.join('\\n')} rows={15}/>`}/>- matchBrackets - Boolean
- matchTags - 'other' | 'none' | 'both'
- styleActiveLine - Boolean
to loads CodeMirror CSS themes from a CDN. There is a list of themes in the textarea below. Try pasting them into the loadTheme prop on the right:
xxxxxxxxxx<button>hello</button>xxxxxxxxxx<ReactPlaygroundStyled matchBrackets={false} matchTags="both" styleActiveLine={false} defaultValue={`<button>hello</button>`}/>The final aim of this library is to deliver complete customisation of each component within the playground. This is done by:
- Props for common requirements e.g. alignment, padding, gutters
- Injecting or modifing wrappers for unlimited flexibility
Props
gutter puts a margin around both the viewer and the editor giving the appearance of a gutter between the two:
xxxxxxxxxx<button>Hello</button>xxxxxxxxxx<ReactPlaygroundStyled defaultValue={'<button>Hello</button>'} gutter={4}/>If you do not want the outer margin on the non-adjcent edges you may want to add negative margin to a playground:
xxxxxxxxxx<button>Hello</button>xxxxxxxxxx<ReactPlaygroundStyled defaultValue={'<button>Hello</button>'} gutter={4} margin={-4}/>padding affects both the editor and viewer:
xxxxxxxxxx<button>Hello</button>xxxxxxxxxx<ReactPlaygroundStyled defaultValue={'<button>Hello</button>'} padding={0}/>minHeightViewer, minWidthViewer, minWidthEditor. For components such as dropdown lists it might be important to force a certain minimum height for the viewer:
xxxxxxxxxx<button>Hello</button>xxxxxxxxxx<ReactPlaygroundStyled defaultValue={'<button>Hello</button>'} minHeightViewer={110}/>Many compents use flex-box for layout this means they may expect to be rendered into a parent with display set to flex. So it is important to be able to control the context components are rendered into. Below some alignment props:
left:
xxxxxxxxxx<button>Hello</button>xxxxxxxxxx<ReactPlaygroundStyled defaultValue={'<button>Hello</button>'} minHeightViewer={110} left/>right:
xxxxxxxxxx<button>Hello</button>xxxxxxxxxx<ReactPlaygroundStyled defaultValue={'<button>Hello</button>'} minHeightViewer={110} right/>top:
xxxxxxxxxx<button>Hello</button>xxxxxxxxxx<ReactPlaygroundStyled defaultValue={'<button>Hello</button>'} minHeightViewer={110} top/>bottom:
xxxxxxxxxx<button>Hello</button>xxxxxxxxxx<ReactPlaygroundStyled defaultValue={'<button>Hello</button>'} minHeightViewer={110} bottom/>Horizontal and vertical alignment can be used together.
bottom right:
xxxxxxxxxx<button>Hello</button>xxxxxxxxxx<ReactPlaygroundStyled defaultValue={'<button>Hello</button>'} minHeightViewer={110} bottom right/>Use fullWidth if you want a component to fill the width of the viewer rather than being centered.
Full Width
xxxxxxxxxx<h3 style={{borderBottom: '1px solid'}}> Full Width</h3>xxxxxxxxxx<ReactPlaygroundStyled defaultValue={`<h3 style={{borderBottom: '1px solid'}}> Full Width</h3>`} minHeightViewer={110} fullWidth/>Themes from Styled-Components
The ThemeBroadcast class can be used to pass styled-components' themes to new React roots e.g. modals, portals or playgrounds. Setting the themeBroadcast prop to an instance of ThemeBroadcast will provide the theme on the context to the React root in the viewer:
Click link to change theme:
xxxxxxxxxx<Button>hello</Button>hello
xxxxxxxxxx<H3>hello</H3>xxxxxxxxxx// import {ThemeBroadcast} from 'react-playground-styled'const themeBroadcast = new ThemeBroadcast({ color: 'green'})const setColor = color => () => themeBroadcast.broadcast({ color: color});const H3 = styled.h3`color: ${({theme}) => theme.color};`;const Button = styled.button`color: ${({theme}) => theme.color};`;<div> <p>Click link to change theme:</p> <button onClick={setColor('green')}>green</button>{' '} <button onClick={setColor('pink')}>pink</button><p/> <ReactPlaygroundStyled defaultValue={`<Button>hello</Button>`} scope={{Button}} themeBroadcast ={themeBroadcast} /> <p /> <ReactPlaygroundStyled defaultValue={`<H3>hello</H3>`} scope={{H3}} themeBroadcast ={themeBroadcast} /></div>Wrappers
There are wrappers components around the editor, the viewer and the whole playground. This allows you to set augment styles on the wrapper (via styled-components), replace the default wrapper or add additional wrappers. Wrapper props are callbacks which accept the default wrapper component as an argument and return a new or changed wrapper. We provide the following wrappers:
- playgroundWrapper
- editorWrapper
- viewerWrapper (outer)
- viewerAlign (inner)
- errorWrapper
- EvalWrapper (NOTE: component not callback)
E.g. provide addition styles to a wrapper, forcing column layout and adding a border:
xxxxxxxxxx<button>Hello</button>xxxxxxxxxx<ReactPlaygroundStyled defaultValue={'<button>Hello</button>'} playgroundWrapper={ Wrapper => styled(Wrapper)` border: 10px solid #555; flex-direction: column-reverse;` } scope={{styled}}/>Provide alternative wrapper:
xxxxxxxxxx<button>Hello</button>xxxxxxxxxx<ReactPlaygroundStyled defaultValue={'<button>Hello</button>'} playgroundWrapper={ () => ({children}) => <div children={children}/> } scope={{styled}}/>The EvalWrapper is different to the other wrappers. It should be a component or null rather than a function that returns a component. If null the content will be evaluated without a wrapper otherwise evaluated content will be passed as children to the EvalWrapper component. The EvalWrapper sits inside the new React root in the viewer. So it can be used for binding context to the outer root e.g. this is the long version of how to bind themes to the inner React root. :
Click link to change theme:
xxxxxxxxxx<Button>hello</Button>hello
xxxxxxxxxx<H3>hello</H3>xxxxxxxxxxconst themeBroadcast = new ThemeBroadcast({ color: 'green'})const EvalWrapper = ({ children }) => ( <ThemeChooserProvider themeBroadcast={themeBroadcast} > {children} </ThemeChooserProvider>)const ThemedPlayground = props => ( <ReactPlaygroundStyled {props} EvalWrapper={EvalWrapper} />);const setColor = color => () => themeBroadcast.broadcast({ color: color});const H3 = styled.h3`color: ${({theme}) => theme.color};`;const Button = styled.button`color: ${({theme}) => theme.color};`;<div> <p>Click link to change theme:</p> <button onClick={setColor('green')}>green</button>{' '} <button onClick={setColor('pink')}>pink</button><p/> <ThemedPlayground defaultValue={`<Button>hello</Button>`} scope={{Button}} /> <p /> <ThemedPlayground defaultValue={`<H3>hello</H3>`} scope={{H3}} /></div>Creating your own custom playground
There are many props for configuring appearance so in a style guide with lots of identical playgrounds you do not want to manually configure each one. You should create your own custom playground with presets that suit you e.g.
- borders
- padding
- wrappers
- themes
- background colors
- put things you will need on the scope
Export it from a module import it where needed and use it repeatedly:
xxxxxxxxxx<Button>hello</Button>hello
xxxxxxxxxx<H3>hello</H3>xxxxxxxxxx<em>{add(2,2)}</em>xxxxxxxxxx<em>{minus(5,2)}</em>xxxxxxxxxx// export this to control themesconst themeBroadcast = new ThemeBroadcast({ color: 'brown'})// import * from libconst lib = { add: (a, b) => a + b, minus: (a, b) => a - b, H3: styled.h3`color: ${({theme}) => theme.color};`, Button: styled.button`color: ${({theme}) => theme.color};`}// export defaultconst MyPlayground = props => { // const { scope, ...rest } = props // no object spread in Bublé const rest = {props} const { scope } = props delete(rest.scope) return ( <ReactPlaygroundStyled scope={{lib, scope}} themeBroadcast={themeBroadcast} loadTheme="cobalt" font="consolas, monospace" backgroundColor="orange" playgroundWrapper={ Wrapper => styled(Wrapper)` flex-direction: row-reverse; margin-bottom: 20px; border-radius: 5px; overflow: hidden;` } {rest} /> )};// import MyPlayground from 'my-playground'<div> <MyPlayground defaultValue={`<Button>hello</Button>`}/> <MyPlayground defaultValue={`<H3>hello</H3>`}/> <MyPlayground defaultValue={`<em>{add(2,2)}</em>`}/> <MyPlayground defaultValue={`<em>{minus(5,2)}</em>`}/></div>Thanks
react-playground-styled was created at NCR Edinburgh thanks for letting me open source it. Inspirtation was taken from component-playground from Formidable Labs.
