README.md

react-controls

A collection of (hopefully) reusable general-purpose React controls

Controls based on react-bootstrap

1. Select Dropdown

A control that mimics the ordinary <select>, but in an more cross-browser look-n-feel. It is built on Bootstrap's (react-bootstrap) dropdown button/menu functionality.

Properties - Select Dropdown:

Name	Required	Type	Description	Example
id	No	String	The DOM id of the dropdown element (if not given, a random id will be autogenerated)	select-something
name	No	String	The DOM name of the controlled input element (if given)	something
options	No	Map	A map of options (supersedes all children elements). There is also support for option groups (see notes below)	new Map([['y', 'Year'], ['d', 'Day']'])
className	No	String	The DOM class to be appended for the entire control	something
textClassName	No	String	The DOM class of the text part of the (toggle) button	text
textWidth	No	String, Number	The width of the text part of the (toggle) button	4em
value	No	String	The current value of this input (aka selected option)	foo
defaultValue	No	String	A default value of this input (aka selected option). If value is missing, will essentially build a uncontrolled input.	foo
placeholder	No	String	The placeholder text to be shown when value is null	select...
onChange	Yes	(val) => ()	A callback to be invoked when input has changed
onSelect	No	(val) => ()	A callback to be invoked when an option was selected

Notes:

• You can either supply the options property or provide <option>, (possibly nested into <optgroup>) children elements. If an options map is given, it supersedes all children elements.
• You can also directly supply grouped options via options property; it understands the following shape: [{group: "Group 1", options: <Map>}, ...].
• The onChange callback does not accept a synthetic event as 1st argument (as in <select>), but the changed value instead.
• The onSelect callback (does not exist in <select>) is invoked regardless of if the selected value has changed.

Methods - Select Dropdown

A public method getValue is available and returns the current normalized value. Practically, this will only be needed in case the component instance is created in uncontrolled mode.

Example - Select Dropdown:

var Select = require('react-controls/select-dropdown');
...
var TimespanControl = React.createClass({
  ...
  // Assume TimespanControl has the following props: timespan, setTimespan
  render: function () {
    return (
      <Select
        id={'select-timespan'}
        name={'timespan'}
        value={this.props.timespan}
        textClassName='text'
        onChange={(val) => (this.props.setTimespan(val))}
       >
        <option key={'day'} value={'day'}>{'Day'}</option>
        <option key={'month'} value={'month'}>{'Month'}</option>
        <option key={'year'} value={'year'}>{'Year'}</option>
      </Select>
    );
  },
});

An equivalent way to write the above (with an options map, instead of children elements):

var Select = require('react-controls/select-dropdown');
...
var timespanOptions = new Map([
  ['day', 'Day'], ['month', 'Month'], ['year', 'Year']
]);
var TimespanControl = React.createClass({
  ...
  render: function () {
    return (
      <Select
        id={'select-timespan'}
        name={'timespan'}
        value={this.props.timespan}
        options={timespanOptions}
        textClassName='text'
        onChange={(val) => (this.props.setTimespan(val))}
       />
    );
  },
});

With the above component, you can style some parts of the above control (e.g. the width of the button):

#select-timespan button > .text {
  width: 5em;
}