Checkbox

Example

<vega-checkbox-group>
  <div class="v-mb-xs">
    <vega-checkbox identifier="apple">
      Apple
    </vega-checkbox>
  </div>
  <div class="v-mb-xs">
    <vega-checkbox identifier="banana">
      Banana
    </vega-checkbox>
  </div>
  <div>
    <vega-checkbox identifier="orange">
      Orange
    </vega-checkbox>
  </div>
</vega-checkbox-group>

  const checkboxes = document.querySelector('vega-checkbox-group');
  checkboxes.vegaFlexProp = {
      gap: 'size-8',
      direction: 'col',
      breakpoint: 'None',
      alignItem: 'start',
      justifyContent: 'start',
      margin: '0',
    };
  checkboxes.value = ['apple', 'banana'];

Note: The above example uses Vanilla JS. If you would like to use React, Angular, or Vue, please consult Storybook.

Usage

Checkboxes are used for providing single or multiple selection fields on a page. They are used when a user may choose any number of choices (zero or many) from a selection of options. Checking one box does not uncheck any others.

Checkboxes are made up of two main elements: vega-checkbox-group, which specifies the grouping of the options, and vega-checkbox, which references the individual checkboxes.

Checkbox (vega-checkbox) Properties

Checkbox Group (vega-checkbox-group) Properties

For vega-checkbox-group, you may modify various flex attributes such as gap, direction, breakpoint, alignment, justification, and margin using the vegaFlexProp object. For instance, if you wish to change the display direction of the checkbox group, you can change the direction from row to col.

Example

const checkboxes = document.querySelector('vega-checkbox-group');
checkboxes.vegaFlexProp = {
    gap: 'size-8',
    direction: 'col',
    breakpoint: 'None',
    alignItem: 'start',
    justifyContent: 'start',
    margin: '0',
};

Note

• The identifier of each checkbox in vega-checkbox-group component can be required but the identifier should not be empty.
• If some checkboxes are checked by default, the value property of vega-checkbox-group should be set, and the checked property of vega-checkbox has no effect.

const checkboxes = document.querySelector('vega-checkbox-group');
checkboxes.value = ['xxx', 'xxx'];

Obtaining the value of a checkbox

There are a few ways of obtaining the value of a selected checkbox.

Method 1: Obtain the value from the value attribute of vega-checkbox-group.

var group = document.getElementById('checkbox-group-id');
console.log(group.value);

Method 2: To obtain multiple values, you may loop through all selected checkboxes.

var values = [];
document.querySelectorAll('vega-checkbox-group input:checked').forEach(cbx => {
    values.push(cbx.value);
});

Method 3: You may use the vega-checkbox without using vega-checkbox-group which behaves similarly to <input type="checkbox"/> in standard HTML.

Method 4: If using checkboxes within vega-form, ideally you will want to use its native getValue method. The behavior is such that

1. While vega-checkbox has an identifier (e.g. <vega-checkbox identifier='testValue'></vega-checkbox>), it will return testValue when checked, and '' when unchecked.
2. While vega-checkbox does not have an identifier (e.g. <vega-checkbox></vega-checkbox>), it will return true if the vega-checkbox is checked. Otherwise it will return false.

Example

<vega-checkbox identifier="xxx" checked="true|false" disabled="true|false"> Label </vega-checkbox>

setValue method

Since the value property is only set by the component, the value should not be set directly. Instead you can call setValue method to set the value.

const checkbox = document.querySelector('vega-checkbox');

// While checkbox has  no identifier attribute, set value to true or false to change checked status.
checkbox.setValue(true);
checkbox.setValue(false);

// While checkbox has an identifier attribute,  set 'identifier value'/'' to change the checked status.
checkbox.setValue('${identifier value}');
checkbox.setValue('');

Events

When a checkbox is checked or unchecked, it will dispatch the vegaChange event. You may add an event listener to either vega-checkbox-group or vega-checkbox.

If the validation result is changed, it will dispatch the vegaValidate event. The event listener can only be added to vega-checkbox-group.

Examples

<!-- React -->
// On a group
<VegaCheckboxGroup onVegaChange={ (e) => { console.log(e.currentTarget.value) } } ... ></VegaCheckboxGroup>

// On a single checkbox
<VegaCheckbox onVegaChange={ (e) => { console.log(e.currentTarget.value) } } ... ></VegaCheckbox>

<!-- vue.js 3.X -->
// On a group
<vega-checkbox-group @vegachange="method" ...></vega-checkbox-group>

// On a single checkbox
<vega-checkbox @vegachange="method" ...></vega-checkbox>

<!-- Javascript -->
document.getElementById("checkbox_group_id").addEventListener("vegaChange", (e) => {
console.log(e.currentTarget.value) }) document.getElementById("checkbox_id").addEventListener("vegaChange",
(e) => { console.log(e.currentTarget.value) })

For more details, view in Storybook.

Accessibility

• Ensures ARIA attributes are allowed for an element’s role.
• All ARIA attributes must have valid values.
• The contrast between foreground and background colors meets WCAG 2 AA contrast ratio thresholds.
• Every id attribute value must be unique.
• Form fields must not have multiple label elements.
• Every form element must not be solely labeled using the title or aria-describedby attributes.
• Every form element must have a label.
• Nested interactive controls are not announced by screen readers.

Best Practices

• A checkbox is best represented by a small square, which will contain either an X or a checkmark when selected.
• Ideally checkboxes should be presented as vertical lists, with only one choice per line. Horizontal lists can result in ambiguity as to which label is associated with which checkbox.

Do

Don't

• Wording on checkboxes should be positive. In other words, selecting will perform an action, instead of preventing an action.
• Labels should be explicitly associated with each checkbox; checking on it should result in the checkbox itself being selected.
• Checkboxes are best designed for changing settings, and not as action buttons; for that purpose you should use a button.