react-check-button-group
Stateful or Stateless React component for a group of checkbox
Table of Contents
Description
This component will generate a group of checkboxes, each enriched with a unique ID and accompanied by a label. It may be stateless or stateful, depending on parameter isStateful. As such it can be used as independent and self-maintained (stateful), or within a managed framework like Redux, Flux etc. (stateless). Please see below about isStateful parameter for details.
The generated HTML will look like:
<div class='groupClassName'}> <!-- div for whole group -->
<div class='itemClassName'> <!--div for each item -->
<input type='checkbox' class='inputClassName id='[unique-id]' name='name' value='value' />
<label class='labelClassName' for='[unique-id]'>Label</label>
</div>
...
</div>
Note that this component does not add any FORM element and leaves that entirely to consumer if needed.
Syntax
<ReactCheckButtonGroup
options={['One', 'Two', 'Three']} [required param]
name="number" [required param]
isStateful={true}
value=["Two","One"]
onChange={function(checkedValues) {console.log("New values: ", checkedValue);}}
fireOnMount={false}
itemClassName="cssForItem"
inputClassName="cssForInput"
labelClassName="cssForLabel"
groupClassName="cssForAll"
/>
Props
options
Type: array; required
An array in which each element specifies a single item in the group (item = option = checkbox + its label). Each element can be either a string or an object of the following form:
{
value: 'apple', // required; value attribute of input[type=checkbox]
label: 'Apple', // text label text; if not specified, uses value
itemClassName: 'cssForItem', // class attribute of item, the div encompassing input and label
labelClassName: 'cssForLabel', // class attribute of label
inputClassName: 'cssForInput' // class attribute of input
}
If an element of options is only a string, then value and label are both considered to be equal to this string, and itemClassName, labelClassName and inputClassName as unspecified in this element.
String elements and object elements of above shape can be mixed. For example:
var fruits = [
'Apple',
{value: 'Mandarin_orange', label: 'Mandarin Orange'},
{value: 'Pear', label: 'Pear', itemClassName: 'pear-item', labelClassName: 'pear-label'}
];
<ReactCheckButtonGroup options={options} name="fruit" />
...will yield:
<div>
<div>
<input type='checkbox' name='fruit' value='Apple'/>
<label>Apple</label>
</div>
<div>
<input type='checkbox' name='fruit' value='Mandarin_orange'/>
<label>Mandarin Orange</label>
</div>
<div class='pear-item'>
<input type='checkbox' name='fruit' value='Pear'/>
<label class='pear-label'>Pear</label>
</div>
</div>
</pre>
name
Type: string; required
Attribute `name` for all inputs. This is needed when the checkbox-group is used within a form, because that is what is going to be sent in POST/GET request.
isStateful
Type: boolean; optional, default false
If isStateful=true, then state is maintained and inputs are controlled by this state. In this case, the value parameter is used only on mount to specify the initialy checked input. Later, use onChange callback to be notified about a new value of the group.
If isStateful=false (default), then state is not maintained and checked status of inputs is controlled purely by value parameter. Use this component in stateless group when you want to integrate it into a Redux framework. The onChange callback will signal when the user is trying to select a different checkbox, which you should then use to generate a new value for this component and re-render it. If isStateful is false, the fireOnMount flag (below) has no effect because there is no initial state.
value
Type: string; optional, default none
The checkboxto be checked. It is specified by its value. In example above, this could be Apple or Mandarin_orange.
Note: This parameter has different meaning depending on value of isStateful parameter - please see description of this parameter for details.
onChange
Type: function; optional, default void
A function to be called when a different checkbox is selected. If user clicks on a checkbox which is already checked, this function will NOT be called. The function will be passed a single parameter - value of the checkbox.
Note: This parameter has different meaning depending on value of isStateful parameter - please see description of this parameter for details.
fireOnMount
Type: boolean; optional, default false
If set to true and onChange is specified, the onChange function will be called on mount with the defaultValue as parameter.
Note: in case isStateful is set to false, this flag has no effect, because there is no initial state to be fired.
inputClassName
Type: string; optional, default none
If specified, it will populate all inputs' class attributes. If any option from options parameter specifies a different inputClassName, it will have priority over this one.
labelClassName
Type: string; optional, default none
If specified, it will populate all labels' class attributes. If any option from options parameter specifies a different labelClassName, it will have priority over this one.
itemClassName
Type: string; optional, default none
If specified, it will populate all class attributes of div's containing checkbox-label groups. If any option from options parameter specifies a different itemClassName, it will have priority over this one.
groupClassName
Type: string; optional, default none
If specified, it will populate class attribute of the div encompassing the whole group of items.
Examples
Examples are provided in the project. Please download the project by running "git clone git@github.com:dmaksimovic/react-check-button-group.git" in command line, and then follow the README files in each:
- Redux-example - The react-check-button-group used in a Redux implementation
- Stateful-example - The react-check-button-group used in independent fashion