Checkbox

The Checkbox control allows selecting one or several options from a number of options. You can set a value associated with a checkbox for form submitting. The control's API allows you to render checkboxes as already checked or disabled and adjust the appearance of a checkbox by applying a custom style and adding a text label.

Related resources

• Get the widget by installing the @svar-ui/react-core package.
• Check Checkbox API Reference to see the list of configuration properties and events.
• Explore the samples to visualize the available features.

Initialization

To add a Checkbox instance into your application, you need to complete two steps:

• import the source file of the control on a page:

App.jsx

import { Checkbox } from "@svar-ui/react-core";

• apply the <Checkbox> tag to initialize a checkbox:

App.jsx

<Checkbox />

A default checkbox is rendered unchecked with no label.

Setting the name attribute

While the checkbox's name is not visible in the user interface, it is necessary when a form is submitted and data with the checkbox's state is sent to the server.

You can set the name for a checkbox via the inputValue API property.

<Checkbox inputValue="1" />

Related sample: Checkbox

Setting the checkbox state

A checkbox is initialized on a page in the unchecked state. You can control the checked/unchecked state of the control via the value property. To check a checkbox, set its value property to true:

<Checkbox value={true}/> 

Related sample: Checkbox

Getting the current state of a checkbox

It is possible to get the state of a checkbox at the moment. For this, you need:

• specify a state variable that will contain the state of the checkbox (it may contain the initial state):

import { useState } from "react";
import { Checkbox } from "@svar-ui/react-core";

const [state, setState] = useState(true);

• pass the state variable to the value prop of the control and update it from the control's onChange handler:

<Checkbox value={state} onChange={({ value }) => setState(value)} />

If you name your state variable value, you can use the same name in your hook:

import { useState } from "react";
import { Checkbox } from "@svar-ui/react-core";

const [value, setValue] = useState(true);

<Checkbox value={value} onChange={({ value }) => setValue(value)} />

After that the state variable will be updated on each change of the checkbox.

Related sample: Checkbox

Catching the change of a checkbox state

The API of the control allows you to catch the change of the state by handling the change event - in React this is exposed as the onChange prop. Inside the handler you can get the state of the checkbox in the following way:

function handleChange({ value, inputValue }) {
  console.log(value);
}

<Checkbox onChange={handleChange} />

The handler function of the onChange event receives an object with the state of the selected checkbox and its name.

Adding a label

A default checkbox has no label. If you need a label for a checkbox, make use of the label property:

<Checkbox label="myCheckbox" />

By default, a label is placed to the right of a checkbox.

Using the left-side label

It is also possible to put a label to the left of a checkbox with the help of the Field component.

You need to take the following steps:

• include the Field source file on a page and use the <Field> component with the necessary props:
  • add a desired label via the label property
  • set the type="checkbox" property for the Field component
  • set the position="left" property to place the label to the left of the checkbox
  • provide the render function (children) that receives the id and renders the Checkbox

import { Checkbox, Field } from "@svar-ui/react-core";

<Field label="Checkbox" type="checkbox" position="left">
  {(id) => <Checkbox id={id} />}
</Field>

After that, the Field will render the label on the left and the Checkbox on the right, binding them by id.

Related sample: Checkbox

Setting the disabled state

Whenever you need to render a disabled checkbox, you can do it with the help of the disabled property set to true.

<Checkbox label="Disabled checked checkbox" disabled={true} />

It is also possible to set the disabled state for a checkbox by declaring the property with no value:

<Checkbox disabled />

Related sample: Checkbox

Styling a checkbox

The appearance of checkboxes is defined by the chosen skin. However, it is possible to redefine the look of a particular checkbox by applying custom inline CSS styles via the style property. As a value of the property, set a string with necessary style attributes:

<Checkbox label="Check" value="1" style="background:red;" />

Grouping checkboxes

When you have a number of checkboxes, it can be useful to combine them into groups. Grouping checkboxes makes it easy to arrange them according to the requirements of your application and check/uncheck several controls on initialization of a group.

The CheckboxGroup control allows you to create groups of checkboxes. It has several props:

• options - an array of checkboxes to be grouped, each checkbox is presented as an object with a value and a label
• value - an array of values of checked checkboxes
• type - a string with the type of arranging checkboxes in a group, can be "inline" or "grid"

Making a group

To create a Checkbox Group instance on a page, you need to complete the following steps:

• import the source file of the control on a page:

App.jsx

import { CheckboxGroup } from "@svar-ui/react-core";

• apply the <CheckboxGroup> tag to initialize the control:

App.jsx

<CheckboxGroup />

• specify an array of checkboxes' objects to group and use the options prop of the control to point to the array:

App.jsx

const options = [
  { id: 1, label: "Option 1" },
  { id: 2, label: "Option 2" },
  { id: 3, label: "Option 3" },
  // more options
];

<CheckboxGroup options={options} />

Setting the checked checkboxes

You can declare which checkbox in a group will be checked. Use the value property for this purpose.

import { useState } from "react";

const options = [
  { id: 1, label: "Option 1" },
  { id: 2, label: "Option 2" },
  { id: 3, label: "Option 3" },
  { id: 4, label: "Option 4" },
  { id: 5, label: "Option 5" }
];

const [valueGroup1, setValueGroup1] = useState([1, 2]);

<CheckboxGroup options={options} value={valueGroup1} onChange={({ value }) => setValueGroup1(value)} />

As a result, the first and the second checkboxes in the group given above will be checked:

Getting values of checked checkboxes

You can get the currently checked checkbox values in the following way:

• specify a state variable that will contain the value of the control:

import { useState } from "react";

const [checked, setChecked] = useState([1, 2]);

const options = [
  { id: 1, label: "Option 1" },
  { id: 2, label: "Option 2" },
  { id: 3, label: "Option 3" },
  // more options
];

• pass the state variable to the value prop of the control and update it from the onChange handler:

<CheckboxGroup options={options} value={checked} onChange={({ value }) => setChecked(value)} />

If you name your state variable value, you can use the same name in your hook:

import { useState } from "react";

const [value, setValue] = useState([1, 2]);

const options = [
  { id: 1, label: "Option 1" },
  { id: 2, label: "Option 2" },
  { id: 3, label: "Option 3" },
  // more options
];

<CheckboxGroup options={options} value={value} onChange={({ value }) => setValue(value)} />

The value assigned to the state variable will be updated on each change of the checked checkboxes in the group.

Setting the type of grouping

Besides arranging checkboxes in a group in a usual way - one under another as in a list, there are two other options available with the type property:

1. You can place checkboxes inline, i.e. in a row, by using the type="inline" property:

import { useState } from "react";

const options = [
  { id: 1, label: "Option 1" },
  { id: 2, label: "Option 2" },
  { id: 3, label: "Option 3" },
  { id: 4, label: "Option 4" },
  { id: 5, label: "Option 5" },
];

const [valueGroup2, setValueGroup2] = useState([2, 3]);

<CheckboxGroup options={options} type="inline" value={valueGroup2} onChange={({ value }) => setValueGroup2(value)} />

2. One more way of grouping checkboxes is to put them into columns with the help of the type="grid" property:

import { useState } from "react";

const options = [
  { id: 1, label: "Option 1" },
  { id: 2, label: "Option 2" },
  { id: 3, label: "Option 3" },
  { id: 4, label: "Option 4" },
  { id: 5, label: "Option 5" },
];

const [valueGroup3, setValueGroup3] = useState([3, 4]);

<CheckboxGroup options={options} type="grid" value={valueGroup3} onChange={({ value }) => setValueGroup3(value)} />