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 wx-svelte-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.svelte

<script>
    import { Checkbox } from "wx-svelte-core";
</script>

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

App.svelte

<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 name API property.

<Checkbox name="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 variable that will contain the state of the checkbox (it may contain the initial state):

<script>
    import { Checkbox } from "wx-svelte-core";

    let state = true;
</script>

• bind the variable to the checked property of the control:

<Checkbox bind:checked={state} />

If the name of the variable matches its value, you can use the shorthand while binding the property:

<script>
    import { Checkbox } from "wx-svelte-core";

    let checked = true;
</script>

<Checkbox bind:checked />

After that the value assigned to the bound variable will be updated on each change of the state 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. Inside the event you can get the state of the checkbox in the following way:

<script>
    function handleChange(ev) {
        const newState= ev.detail;
        console.log(newState); 
        // => {value: true, name: 'Option 1'}
    }
</script>

<Checkbox name="Option 1" on:change={handleChange}/>

The handler function of the change event takes the CustomEvent object as a parameter and in its detail property it contains an object with the value of a 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, declare the <Field> tag and complete it 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
  • specify the id variable to bind the field to the checkbox control

<script>
    import { Checkbox, Field } from "wx-svelte-core";
</script>

<Field label="Checkbox" type="checkbox" position="left" let:id/>

After that, wrap the checkbox in question into the <Field> tags and specify the id property for the checkbox:

<Field label="Checkbox" type="checkbox" position="left" let:id>
    <Checkbox {id} />
</Field>

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 /> <!-- equals to "disabled={true}" -->

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.svelte

<script>
    import { CheckboxGroup } from "wx-svelte-core";
</script>

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

App.svelte

<CheckboxGroup />

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

App.svelte

<script>
    let options = [
        { value: 1, label: "Option 1" },
        { value: 2, label: "Option 2" },
        { value: 3, label: "Option 3" },
        // more options
    ];
</script>

<CheckboxGroup {options} />

Setting the checked checkboxes

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

<script>
    let options = [
        { value: 1, label: "Option 1" },
        { value: 2, label: "Option 2" },
        { value: 3, label: "Option 3" },
        { value: 4, label: "Option 4" },
        { value: 5, label: "Option 5" }
    ];

    let valueGroup1 = [1,2];
</script>

<CheckboxGroup {options} bind:value={valueGroup1} />

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 value in the following way:

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

<script>
    let checked = [1,2];

    let options = [
        { value: 1, label: "Option 1" },
        { value: 2, label: "Option 2" },
        { value: 3, label: "Option 3" },
        // more options
    ];
</script>

• bind the variable to the value property of the control:

<CheckboxGroup {options} bind:value={checked} />

If the name of the variable matches its value, you can use the shorthand while binding the property:

<script>
    let value = [1,2];

    let options = [
        { value: 1, label: "Option 1" },
        { value: 2, label: "Option 2" },
        { value: 3, label: "Option 3" },
        // more options
    ];
</script>

<CheckboxGroup {options} bind:value />

The value assigned to the bound 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:

<script>
    let options = [
        { value: 1, label: "Option 1" },
        { value: 2, label: "Option 2" },
        { value: 3, label: "Option 3" },
        { value: 4, label: "Option 4" },
        { value: 5, label: "Option 5" },
    ];

    let valueGroup2 = [2, 3];
</script>

<CheckboxGroup {options} type="inline" bind:value={valueGroup2} />

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

<script>
    let options = [
        { value: 1, label: "Option 1" },
        { value: 2, label: "Option 2" },
        { value: 3, label: "Option 3" },
        { value: 4, label: "Option 4" },
        { value: 5, label: "Option 5" },
    ];

    let valueGroup3 = [3, 4];
</script>

<CheckboxGroup {options} type="grid" bind:value={valueGroup3} />