dozoisch/react-prop-types

React PropType utilities

react-prop-types

This is a library of some custom validators for React components properties. Initially they were part of the React-Bootstrap project.

Usage

All validators can be imported as

import elementType from 'react-prop-types/lib/elementType';
// or
import { elementType } from 'react-prop-types';
...
propTypes: {
  someProp: elementType

or

import * as CustomPropTypes from 'react-prop-types';
// and then used as usual
propTypes: {
  someProp: CustomPropTypes.elementType

If you use webpack and only want to bundle the validators you need, prefer the following approach:

import elementType from 'react-prop-types/lib/elementType'

---

all(...arrayOfValidators)

This validator allows to have complex validation like this:

propTypes: {
  vertical:  React.PropTypes.bool,
  /**
   * Display block buttons, only useful when used with the "vertical" prop.
   * @type {bool}
   */
  block: CustomPropTypes.all(
    React.PropTypes.bool,
    function(props, propName, componentName) {
      if (props.block && !props.vertical) {
        return new Error('The block property requires the vertical property to be set to have any effect');
      }
    }
  )

All validators will be validated one by one, stopping on the first failure.

The all() validator will only succeed when all validators provided also succeed.

---

elementType

Checks whether a property provides a type of element. The type of element can be provided in two forms:

• tag name (string)
• a return value of React.createClass(...)

Example

propTypes: {
  componentClass: CustomPropTypes.elementType

Then, componentClass can be set by doing:

<Component componentClass='span' />

or

const Button = React.createClass(...);
...
<Component componentClass={Button} />

---

isRequiredForA11y(requiredType)

This is kind of React.PropTypes.<type>.isRequired with the custom error message: The prop <propName> is required for users using assistive technologies

Example

propTypes: {
  /**
   * An html id attribute, necessary for accessibility
   * @type {string}
   * @required
   */
  id: CustomPropTypes.isRequiredForA11y(React.PropTypes.string)

---

keyOf(object)

Checks whether provided string value is one of provided object's keys.

Example

const SIZES = {
  'large': 'lg',
  'small': 'sm'
}

propTypes: {
  size: CustomPropTypes.keyOf(SIZES)
}

// this validates OK
<Component size="large" />

// this throws the error `expected one of ["large", "small"]`
<Component size="middle" />

A more extended example

const styleMaps = {
  CLASSES: {
    'alert': 'alert',
    'button': 'btn'
  ...
  SIZES: {
    'large': 'lg',
    'medium': 'md',
    'small': 'sm',
    'xsmall': 'xs'
  }
...
propTypes: {
  /**
   * bootstrap className
   * @private
   */
  bsClass: CustomPropTypes.keyOf(styleMaps.CLASSES),
  /**
   * Style variants
   * @type {("default"|"primary"|"success"|"info"|"warning"|"danger"|"link")}
   */
  bsStyle: CustomPropTypes.keyOf(styleMaps.STYLES),
  /**
   * Size variants
   * @type {("xsmall"|"small"|"medium"|"large")}
   */
  bsSize: CustomPropTypes.keyOf(styleMaps.SIZES)
}

---

mountable

Checks whether a prop provides a DOM element The element can be provided in two forms:

• Directly passed
• Or passed an object that has a render method

Example

propTypes: {
  modal: React.PropTypes.node.isRequired,
  /**
   * The DOM Node that the Component will render it's children into
   */
  container: CustomPropTypes.mountable

A variant of usage <Overlay container={this}>

const Example = React.createClass({
  getInitialState(){ return { show: true } },
  toggle(){ this.setState({ show: !this.state.show }) },

  render(){
    const tooltip = <Tooltip>Tooltip overload!</Tooltip>;

    return (
      <div>
        <Button ref='target' onClick={this.toggle}>
          Click me!
        </Button>

        <Overlay container={this}>
          { tooltip }
        </Overlay>
      </div>
    );
  }
});

React.render(<Example/>, mountNode);

---

singlePropFrom(...propertyNames)

Used when it needs to assure that only one of properties can be used.

Imagine we need the value for our ButtonInput component could be set by only one of two ways:

• through children
• through value preperty But not both.

Like this:

<ButtonInput> ButtonValue </ButtonInput>

or

<ButtonInput value="ButtonValue" />

But this should throw the only one of the following may be provided error

<ButtonInput value="ButtonValue"> SomeChildren </ButtonInput>

The possible solution

import singlePropFrom from 'react-prop-types/lib/singlePropFrom';

const typeList = [React.PropTypes.number, React.PropTypes.string];

function childrenValueValidation(props, propName, componentName) {
  let error = singlePropFrom('children', 'value')(props, propName, componentName);
  if (!error) {
    const oneOfType = React.PropTypes.oneOfType(typeList);
    error = oneOfType(props, propName, componentName);
  }
  return error;
}

...

ButtonInput.propTypes = {
  children: childrenValueValidation,
  value: childrenValueValidation

---

deprecated(propType, explanation)

Helps with properties deprecations

Example

propTypes: {
  collapsable: deprecated(React.PropTypes.bool, 'Use "collapsible" instead.')

In development mode it will write to the development console of a browser:

"collapsable" property of "ComponentName" has been deprecated.
Use "collapsible" instead.

Notice: this custom validator uses 'warning' package under the hood. And this package uses console.error channel instead of console.warn.