React Polymorph

React Polymorph is a UI framework for React, that separates logic, markup and theming of components. It's inspired by react-toolbox (but more flexible), powered by CSS Modules and harmoniously integrates with your webpack workflow, although you can use any other module bundler.

Why?

• Existing React UI frameworks are too hard to customize.
• Overriding css styles is not enough for complex components.
• You need multiple variations of a component with shared logic.
• You need multiple, completely unique themes for your components.

How:

Separate monolithic React components into:

1. Component (logic) - Only handle UI logic, do not render markup.
2. Skin (markup) - Only render the markup, delegate to component.
3. Theme (styling) - Only concerned about styling your skin.

Installation & Usage

React Polymorph can be installed as an npm package:

$ npm install --save react-polymorph

Usage in Webpack Projects

npm install --save style-loader css-loader sass-loader

module: {loaders: [{test: /\.scss$/,loaders: ['style?sourceMap','css?sourceMap&modules&localIdentName=[name]_[local]&importLoaders=1','sass?sourceMap']},// your other loaders …]},

Now you can import and use components like this in your app:

importReactfrom"react";import{Input}from"react-polymorph/lib/components";import{InputSkin}from"react-polymorph/lib/skins/simple/InputSkin";import{InputTheme}from"react-polymorph/lib/themes/simple/InputTheme";constMyInput=()=>(<Input// <- Logicskin={InputSkin}// <- Markuptheme={InputTheme}// <- Stylinglabel="My Input"// <- Component prop/>);

Each component needs a skin to render markup and will receive its styles (css/scss) via a theme.

Theme Provider

Of course this would be a lot of code just to render a simple input. That's why you should always use a theme provider to inject skins and themes into all components below the ThemeProvider automatically (components can be arbitrarily deep nested).

importReactfrom"react";import{Input}from"react-polymorph/lib/components";import{SimpleSkins}from"react-polymorph/lib/skins/simple";import{SimpleTheme}from"react-polymorph/lib/themes/simple";// Notice that we don't have to pass any skin or theme to the inputs:constMyForm=()=>(<div><Inputlabel="First Name"/><Inputlabel="Last Name"/></div>);constSimpleFormApp=()=>(<ThemeProviderskins={SimpleSkins}theme={SimpleTheme}><MyForm/></ThemeProvider>);

Release Managament

• Starting with 1.0.0 all future releases will follow semver semantics:

  • patch (eg: 1.0.x) for API compatible bug fixes
  • minor (eg.: 1.x.0) for API compatible new features
  • major (eg: 2.0.0) for API breaking changes

• For early integration of upcoming release changes we use the following conventions:

  • [current version]-next.x to tag changes for upcoming releases (as we cannot know the necessary semver for the final release including all the changes). x in this case is simply a number that is increased and can be thought of like "slots" for temporary releases

  • All temporary releases should be published with the next npm dist tag via: npm publish --tag next so that they are not automatically tagged with the default latest npm tag.

• The master branch only includes commits of final releases

• release/x.x.x branches are created as soon as we cut a release and know the correct semver - they are always targeting the master branch + should be well documented. They can include many release candidates which should be tagged like [next releaes]-rc.X where you increment X per release candidate until we are confident that the release is ready to be published under its normal version.

How to publish a temporary release

Temporary releases are useful for testing specific changes in your project PRs without making public releases that might confuse others and are not following semver.

1. Create a dedicated branch for your bug/feature/chore
2. Run npm view react-polymorph dist-tags.next to see the latest release version the next npm dist-tag is currently pointing to (this will look something like this: 1.0.0-next.1)
3. Increase the next.X number by one (e.g: npm version 1.0.0-next.2) to create a new git tag via.
4. Publish the release candidate with npm publish --tag next (to assign the next dist-tag instead of latest)
5. Reference your release candidate version in your project PR

How to publish a stable release

Stable releases are the next public version change of react-polymorph combining all previous temporary releases into a semver based release:

1. Create a new release/x.x.x branch based on develop (following semver based on changelog)
2. Update the version in package.json to the planned release version (do not tag it)
3. Update the CHANGELOG.md to assign the new release version to the last changes and upcoming changes
4. Setup a PR targetting master for the relase branch on Github and document the changes since last release
5. Publish a release candidate to npm (e.g: 1.0.1-rc.1)
6. Integrate and test the release candidate
7. Iterate on the release via release candidates until its ready to be merged
8. Merge the release PR into master on Github and then master back into develop

Components and Skins

React-polymorph comes with simple themes & skins out of the box, but anything is customizable.

Imagine you need a standard text Input component for text and a NumericInput for floating point numbers. The only difference is the logic of the component, in both cases it is "just" an input field showing some text:

---

Input

Represents a single-line input field.

Example Usage:

importReactfrom"react";import{Input}from"react-polymorph/lib/components";// Standard input component:constMyStandardInput=()=>(<Inputlabel="Input with max. 5 Characters"maxLength={5}/>);

Input Props:

typeInputProps={autoFocus: boolean,className?: ?string,disabled?: boolean,error: string|Element<any>,label?: string|Element<any>,maxLength?: number,minLength?: number,onBlur?: Function,onChange?: Function,onFocus?: Function,onKeyPress?: Function,placeholder?: string,readOnly: boolean,setError?: Function,skin?: ComponentType<any>,theme: ?Object,themeOverrides: Object,value: string};

---

Numeric Input

Component specialized in guiding the user to enter correct floating point numbers.

Example Usage:

importReactfrom"react";import{NumericInput}from"react-polymorph/lib/components";import{InputSkin}from"react-polymorph/lib/skins/simple";constMyNumericInput=()=>(<NumericInputlabel="Amount"placeholder="0.000000"decimalPlaces={6}bigNumberFormat={{decimalSeparator: '.',groupSeparator: ','}}/>);

Expected Behavior:

Since there is no web standard on how to build numeric input components, here is the specification we came up with that serves our purposes in the best way:

• Only numeric digits [0-9] and decimal separators (configurable via bigNumberFormat prop) can be entered.
• When invalid characters are pasted as input, nothing happens
• When a second decimal separators is entered it replaces the existing one and updates the fraction part accordingly
• Group separators cannot be deleted but the cursor should jump over them when DEL or BACKSPACE keys are used
• It's possible to replace the whole number or parts of it (even the decimal separator) by inserting another number.

Props:

The NumericInput is based on the Input component and extends it's functionality:

typeNumericInputProps={// Input props:autoFocus?: boolean,className?: string,context: ThemeContextProp,disabled?: boolean,error?: string,label?: string|Element<any>,onBlur?: Function,onChange?: Function,onFocus?: Function,placeholder?: string,readOnly?: boolean,skin?: ComponentType<any>,theme: ?Object,themeId: string,themeOverrides: Object,// Numeric input specific props:allowSigns?: boolean,bigNumberFormat?: BigNumber.Format,decimalPlaces?: number,roundingMode?: BigNumber.RoundingMode,value: ?BigNumber.Instance,};

value

Must be an instance of BigNumberonChange also returns an instance of BigNumber after any user changes.

allowSigns

Is true by default, if false the user cannot enter negative numbers.

decimalPlaces

No restriction by default (any number of decimal places allowed). Can be set to fix the decimal places to a specific amount.

bigNumberFormat

You can configure the number format by passing in any valid bignumber.js FORMAT option

roundingMode

You can configure the rounding mode by passing in any valid bignumber.js ROUNDING_MODE option

---

Textarea

Simple component that represents an input which can receive multiple lines of text.

Example Usage:

importReactfrom"react";import{TextArea}from"react-polymorph/lib/components";constMyTextArea=()=>(<TextArealabel="Textarea with fixed amount of rows to start with"placeholder="Your description here"rows={5}/>);

TextArea Props:

typeTextAreaProps={autoFocus: boolean,autoResize: boolean,className?: string,context: ThemeContextProp,disabled?: boolean,label?: string|Element<any>,error?: string|Node,maxLength?: number,minLength?: number,onBlur?: Function,onChange?: Function,onFocus?: Function,placeholder?: string,rows?: number,skin?: ComponentType<any>,theme: ?Object,themeId: string,themeOverrides: Object,value: string};

---

Button

Represents a clickable area.

Example Usage:

importReactfrom"react";import{Button}from"react-polymorph/lib/components";constMyButton=()=>(<Buttonlabel="Button label"/>);

Button Props:

typeButtonProps={className?: string,disabled?: boolean,label?: string|Element<any>,loading: boolean,onClick?: Function,skin?: ComponentType<any>,theme: ?Object,themeOverrides: Object};

---

Select

The select component is like standard select but with additional logic for adding custom option renderer and opening directions (upward / downward).

Example Usage:

importReactfrom"react";import{Select}from"react-polymorph/lib/components";constCOUNTRIES_WITH_FLAGS=[{value: 'EN-gb',label: 'England',flag: flagEngland},{value: 'ES-es',label: 'Spain',flag: flagSpain},{value: 'TH-th',label: 'Thailand',flag: flagThailand},{value: 'EN-en',label: 'USA',flag: flagUSA}];constMySelect=()=>(<Selectlabel="Countries"options={COUNTRIES_WITH_FLAGS}optionRenderer={option=>{return(<divclassName={styles.customOptionStyle}><imgsrc={option.flag}/><span>{option.label}</span></div>);}}/>);

Select Props:

typeSelectProps={allowBlank: boolean,autoFocus: boolean,className?: string,error?: string|Element<any>,label?: string|Element<any>,isOpeningUpward: boolean,onBlur?: Function,onChange?: Function,onFocus?: Function,optionRenderer?: Function,options: Array<any>,placeholder?: string,skin?: ComponentType<any>,theme: ?Object,themeOverrides: Object,value: string};

---

Checkbox

Represents a component which can toggle between checked and unchecked state.

Example Usage:

importReactfrom"react";import{Checkbox}from"react-polymorph/lib/components";constMyCheckbox=()=>(<Checkboxlabel="My checkbox"/>);

Checkbox Props:

typeCheckboxProps={checked: boolean,className?: string,context: ThemeContextProp,disabled?: boolean,label?: string|Element<any>,labelLeft?: string|Element<any>,labelRight?: string|Element<any>,onChange?: Function,onBlur?: Function,onFocus?: Function,skin?: ComponentType<any>,theme: ?Object,themeId: string,themeOverrides: Object};

---

Switch

Like checkbox but uses a different skin part.

Example Usage:

importReactfrom"react";import{Checkbox}from"react-polymorph/lib/components";constMySwitch=()=>(<Checkboxlabel="My switch"/>);

Switch Props -> see Checkbox (above)

---

Toggler

Like checkbox but uses a different skin part.

Example Usage:

importReactfrom"react";import{Checkbox}from"react-polymorph/lib/components";constMyToggler=()=>(<CheckboxlabelLeft="Included"labelRight="Excluded"/>);

Toggler Props -> see Checkbox (above)

---

Modal

The modal is component which wraps its children as standard dialog. As is shown in example, modal can have multiple other polymorph components:

Example Usage:

importReactfrom"react";import{Modal,Button}from"react-polymorph/lib/components";constMyModal=props=>(<ModaltriggerCloseOnOverlayClick={false}><h1className={styles.modalTitle}>
Are you sure you want to delete this thing?
</h1><divclassName={styles.buttonsContainer}><Buttonlabel="Cancel"onClick={closeModalCallback}/><Buttonlabel="Delete"onClick={closeModalCallback}/></div></Modal>);

Modal Props:

typeModalProps={contentLabel: string|Element<any>,isOpen: boolean,onClose?: Function,skin?: ComponentType<any>,triggerCloseOnOverlayClick: boolean,theme: ?Object,themeOverrides: Object};

---

Autocomplete

The autocomplete input is specialized to help users to select between multiple suggested words depending on entered letters:

Example Usage:

importReactfrom"react";import{Autocomplete}from"react-polymorph/lib/components";constMyAutocomplete=props=>(<Autocompletelabel="Recovery phrase"placeholder="Enter recovery phrase"suggestedWords={SUGGESTED_WORDS}placeholder="Enter mnemonic..."maxSelections={12}maxVisibleSuggestions={5}invalidCharsRegex={/[^a-zA-Z]/g}/>);

Autocomplete Props:

typeAutocompleteProps={className?: string,error: ?string,invalidCharsRegex: RegExp,isOpeningUpward: boolean,label?: string|Element<any>,maxSelections?: number,maxVisibleOptions: number,multipleSameSelections: boolean,onChange?: Function,options: Array<any>,preselectedOptions?: Array<any>,placeholder?: string,renderSelections?: Function,renderOptions?: Function,skin?: ComponentType<any>,sortAlphabetically: boolean,theme: ?Object,themeOverrides: Object};

---

Bubble

The bubble component will open up an absolutely positioned speech bubble. This is position in respect to it's closest relatively positioned parent.

Example Usage:

importReactfrom"react";import{Bubble}from"react-polymorph/lib/components";constMyBubble=props=>(<divclassName={{position: "relative"}}><Bubble>
plain bubble
</Bubble></div>);

Bubble Props:

typeBubbleProps={className?: string,isHidden: boolean,isFloating: boolean,isOpeningUpward: boolean,isTransparent: boolean,skin?: ComponentType<any>,theme: ?Object,themeOverrides: Object,targetRef?: Ref<*>,// ref to the target DOM element used for positioning the bubble};

---

Tooltip

The tooltip opens a bubble relative to it's children, containing text or html to display.

Example Usage:

importReactfrom"react";import{Tooltip}from"react-polymorph/lib/components";constMyTooltip=props=>(<Tooltiptip="Description of the child element">
hover over me
</Tooltip>);

Tooltip Props:

typeTooltipProps={className?: string,isAligningRight?: boolean,isBounded?: boolean,isOpeningUpward: boolean,isTransparent: boolean,arrowRelativeToTip: boolean,skin?: ComponentType<any>,theme: ?Object,themeOverrides: Object,tip?: string|Element<any>};

---

Radio

The radio is as simple as possible and does not have much logic:

Example Usage:

importReactfrom"react";import{Radio}from"react-polymorph/lib/components";import{RadioSkin}from"react-polymorph/lib/skins/simple";import{RadioTheme}from"react-polymorph/lib/themes/simple";constMyRadio=props=>(<Radiolabel="My radio"skin={SimpleRadioSkin}theme={RadioTheme}/>);

Radio Props:

typeRadioProps={disabled?: boolean,label?: string|Element<any>,onBlur?: Function,onChange?: Function,onFocus?: Function,selected: boolean,skin?: ComponentType<any>,theme: ?Object,themeOverrides: Object};

Customizing Component Skins

Theme API

Each component has a theme API. This is a plain object which exposes the shape of a component's theme. Each property on the theme API object is a class name assigned to an element within the component's skin and a class definition within the component's theme. Below is the Button's theme API.

{root: '',disabled: ''}

Every component accepts an optional themeOverrides property intended to provide a CSS Module import object which is used by the component to assign a user's local classnames to its DOM nodes. If the component has already been passed a theme prop, the css/scss properties passed via themeOverrides will be merged with the injected theme object. This automatic composition saves the user from manually piecing together custom styles with those of the injected theme that the user may wish to retain. If you want to customize a component's theme, the themeOverrides object must contain the appropriate classname mapping to its documented theme API. In this way, you can add or override classnames on the nodes of a specific component.

Overriding styles in a theme

For example, if you want to override the background-color of Button's injected theme with green:

importReactfrom"react";import{Button}from"react-polymorph/lib/components";import{ButtonSkin}from"react-polymorph/lib/skins/simple";import{ButtonTheme}from"react-polymorph/lib/themes/simple";importthemeOverridesfrom"./GreenButton.css";constGreenButton=props=>(<Button{...props}skin={ButtonSkin}theme={ButtonTheme}themeOverrides={themeOverrides}/>);exportdefaultGreenButton;

themeOverrides

.root {
background-color: green;
}

ButtonTheme

.root {
background-color: blue;
color: white;
border-radius:5px;
}

Result

.root {
background-color: green;
color: white;
border-radius:5px;
}

The user's custom background color overrides Simple theme's blue background.

Compose

Similarly, you can compose your own custom styles with an injected theme

themeOverrides

.root {
text-transform: uppercase;
}

will be composed with

ButtonTheme

.root {
background-color: blue;
color: white;
border-radius:5px;
}

Result

.root {
text-transform: uppercase;
background-color: blue;
color: white;
border-radius:5px;
}

In this case we are composing custom styles with an instance of Button where the Simple ButtonTheme was already injected. If a theme isn't passed to a component, a theme object implementing that component's full theme API is necessary. When implementing a component's full theme, take into account that every classname is there for a reason. You can either provide a component's theme as a prop or pass it through context as described in the next section.

ThemeProvider HOC

ThemeProvider allows you to pass a theme to multiple instances of a component without explicitly passing them a theme prop. Wrap your component tree with ThemeProvider at the desired level in your component hierarchy. You can maintain different themes and themeOverrides for specific portions of your app's tree.

Example Usage:

importReact,{Component}from"react";// componentsimport{ThemeProvider,Modal,FormField,Input,Button}from"react-polymorph/lib/components";// skinsimport{ModalSkin,FormFieldSkin,InputSkin,ButtonSkin}from"react-polymorph/lib/skins/simple";// themesimport{ModalTheme,FormFieldTheme,InputTheme,ButtonTheme}from"react-polymorph/lib/themes/simple";classAppextendsComponent{state={isOpen: true,value: ""};setValue=value=>this.setState({ value });render(){// Custom ThemeconstSimpleTheme={modal: { ...ModalTheme},formfield: { ...FormFieldTheme},input: { ...InputTheme},button: { ...ButtonTheme}};// Custom SkinsconstSimpleSkins={modal: ModalSkin,formfield: FormFieldSkin,input: InputSkin,button: ButtonSkin,};return(<ThemeProviderskins={SimpleSkins}theme={SimpleTheme}><ModalisOpen={this.state.isOpen}triggerCloseOnOverlayClick={false}><div><FormFieldlabel="FormField in Modal"render={props=>(<Input{...props}value={this.state.value}onChange={this.setValue}/>)}/></div><div><ButtononClick={this.props.handleClick}className="primary"label="Submit"/></div></Modal></ThemeProvider>);}}exportdefaultApp;

Customizing all instances of a Component using ThemeProvider

Create a CSS Module theme file for the component you wish to customize, for example for Input & FormField:

input.css

.input {
width:25%;
}
.input:focus {
border-color: green;
width:50%;
}
.input:hover {
border-color: green;
}

formfield.css

.label {
color: green;
font-family:"Lato", sans-serif;
}

Create a theme file that imports each component's custom styles as CSS-Modules object(s). Apply the styles according to the root theme API structure. The root theme API is simply an object whose keys are named after each component in the react-polymorph library. For example, the styles you assign to the input key will be applied to all instances of the Input component nested within ThemeProvider. The same goes for the formfield key and all nested instances of the FormField component.

customInputs.js

importMyCustomInputThemefrom"./css/input.css";importMyCustomFormFieldThemefrom"./css/formfield.css";exportdefault{input: MyCustomInputTheme,formfield: MyCustomFormFieldTheme};

Import your custom theme to pass ThemeProvider's themeOverrides property. This will apply your custom css/scss to all of its nested react-polymorph components. In this example, all 3 instances of the Input and FormField components will have the user's custom css definitions composed with Simple InputTheme and FormFieldTheme.

importReactfrom"react";// componentsimport{ThemeProvider,FormField,Input,NumericInput}from"react-polymorph/lib/components";// skinsimport{SimpleSkins}from"react-polymorph/lib/skins/simple";// themesimport{FormFieldTheme,InputTheme}from"react-polymorph/lib/themes/simple";// the user's custom Input and FormField stylesimportCustomInputsThemefrom"./styles/customInputs.js";constCustomInputs=props=>{constSimpleTheme={input: { ...InputTheme},formfield: { ...FormFieldTheme}};return(<ThemeProviderskins={SimpleSkins}themeOverrides={CustomInputsTheme}theme={SimpleTheme}><FormFieldlabel="Recipient's First Name"render={props=>(<Input{...props}placeholder="Avery"/>)}/><FormFieldlabel="Recipient's Last Name"render={props=>(<Input{...props}placeholder="McKenna"/>)}/><FormFieldlabel="Amount to Send"render={props=>(<NumericInput{...props}placeholder="10.000"/>)}/></ThemeProvider>);};exportdefaultCustomInputs;

You may also pass the entire SimpleTheme object to ThemeProvider and maintain the same functionality without having to import themes specific to the components you're using.

importReactfrom"react";// componentsimport{ThemeProvider}from"react-polymorph/lib/components";// skinsimport{SimpleSkins}from"react-polymorph/lib/skins/simple";// themesimport{SimpleTheme}from"react-polymorph/lib/themes/simple";constApp=()=>(<ThemeProviderskins={SimpleSkins}theme={SimpleTheme}><div>...</div></ThemeProvider>);exportdefaultApp;