# react-check-button-group Stateful or Stateless React component for a group of checkbox

Description
Syntax
Props
- options
- name
- isStateful
- value
- onChange
- fireOnMount
- inputClassName
- labelClassName
- itemClassName
- groupClassName
Examples

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

Table of Contents

Description

Syntax

Props

options

name

isStateful

value

onChange

fireOnMount

inputClassName

labelClassName

itemClassName

groupClassName

Examples