diff --git a/packages/components/src/checkbox-control/README.md b/packages/components/src/checkbox-control/README.md index 2538fda6b3dd05..91b50a09b2d970 100644 --- a/packages/components/src/checkbox-control/README.md +++ b/packages/components/src/checkbox-control/README.md @@ -1,9 +1,57 @@ # CheckboxControl -CheckboxControl component is used to generate a checkbox input field. +Checkboxes allow the user to select one or more items from a set. +![](https://make.wordpress.org/design/files/2019/02/CheckboxControl.png) -## Usage +Selected and unselected checkboxes + +## Table of contents + +1. [Design guidelines](http://#design-guidelines) +2. [Development guidelines](http://#development-guidelines) +3. [Related components](http://#related-components) + +## Design guidelines + +### Usage + +#### When to use checkboxes + +Use checkboxes when you want users to: + +- Select one or multiple items from a list. +- Open a list containing sub-selections. + +![](https://make.wordpress.org/design/files/2019/02/select-from-list.png) + +**Do** +Use checkboxes when users can select multiple items from a list. They let users select more than one item. + +![](https://make.wordpress.org/design/files/2019/02/many-form-toggles.png) + +**Don’t** +Don’t use toggles when a list consists of multiple options. Use checkboxes — they take up less space. + +![](https://make.wordpress.org/design/files/2019/02/checkbox-sublist.gif) + +Checkboxes can be used to open a list containing sub-selections. + +#### Parent and child checkboxes + +Checkboxes can have a parent-child relationship, with secondary options nested under primary options. + +![](https://make.wordpress.org/design/files/2019/02/checkbox-parent.gif) + +When the parent checkbox is *checked*, all the child checkboxes are checked. When a parent checkbox is *unchecked*, all the child checkboxes are unchecked. + +![](https://make.wordpress.org/design/files/2019/02/mixed-checkbox.png) + +If only a few child checkboxes are checked, the parent checkbox becomes a mixed checkbox. + +## Development guidelines + +### Usage Render an is author checkbox: ```jsx @@ -23,20 +71,19 @@ const MyCheckboxControl = withState( { ) ); ``` -## Props +### Props The set of props accepted by the component will be specified below. Props not included in this set will be applied to the input element. -### heading +#### heading A heading for the input field, that appears above the checkbox. If the prop is not passed no heading will be rendered. - Type: `String` - Required: No - -### label +#### label A label for the input field, that appears at the side of the checkbox. The prop will be rendered as content a label element. @@ -45,14 +92,14 @@ If no prop is passed an empty label is rendered. - Type: `String` - Required: No -### help +#### help If this property is added, a help text will be generated using help property as the content. - Type: `String` - Required: No -### checked +#### checked If checked is true the checkbox will be checked. If checked is false the checkbox will be unchecked. If no value is passed the checkbox will be unchecked. @@ -60,9 +107,14 @@ If no value is passed the checkbox will be unchecked. - Type: `Boolean` - Required: No -### onChange +#### onChange A function that receives the checked state (boolean) as input. - Type: `function` - Required: Yes + +## Related components + +- To select one option from a set, and you want to show all the available options at once, use the `RadioControl` component. +- To toggle a single setting on or off, use the `FormToggle` component.