Checkbox

<pc-checkbox>

0.1.0

experimental

Checkboxes allow the user to toggle an option on or off.

<pc-checkbox>Checkbox</pc-checkbox>

Code

Edit

This component works well with standard <form> elements. Please refer to the form controls page to learn more about form submission and client‐side validation.

Demos

Checked

Use the checked attribute to enable the checkbox.

<pc-checkbox checked>Checked</pc-checkbox>

Code

Edit

Indeterminate

Use the indeterminate attribute to make the checkbox indeterminate.

<div class="checkbox-indeterminate">
    <pc-checkbox data-role="all">All options</pc-checkbox>

    <pc-checkbox data-role="option">Option 1</pc-checkbox>
    <pc-checkbox data-role="option" checked>Option 2</pc-checkbox>
    <pc-checkbox data-role="option">Option 3</pc-checkbox>
</div>

<script>
    const group = document.querySelector(".checkbox-indeterminate");
    const allCheckboxes = group.querySelector('[data-role="all"]');
    const optionCheckboxes = Array.from(group.querySelectorAll('[data-role="option"]'));

    function updateAllCheckboxes() {
        const checkedCount = optionCheckboxes.filter((checkbox) => checkbox.checked).length;

        if (checkedCount === optionCheckboxes.length) {
            allCheckboxes.checked = true;
            allCheckboxes.indeterminate = false;
        } else if (checkedCount === 0) {
            allCheckboxes.checked = false;
            allCheckboxes.indeterminate = false;
        } else {
            allCheckboxes.checked = false;
            allCheckboxes.indeterminate = true;
        }
    }

    allCheckboxes.addEventListener("pc-change", () => {
        const isChecked = allCheckboxes.checked;
        allCheckboxes.indeterminate = false;
        optionCheckboxes.forEach((checkbox) => checkbox.checked = isChecked);
    });

    optionCheckboxes.forEach((checkbox) => {
        checkbox.addEventListener("pc-change", updateAllCheckboxes);
    });

    updateAllCheckboxes();
</script>

<style>
    .checkbox-indeterminate pc-checkbox {
        display: block;
    }

    .checkbox-indeterminate pc-checkbox[data-role="all"] {
        margin-block-end: 0.125em;
    }

    .checkbox-indeterminate pc-checkbox[data-role="option"] {
        padding-inline-start: 0.75em;
        border-inline-start: var(--pc-border-width-s) var(--pc-border-style)
            var(--pc-color-surface-border);
    }
</style>

Code

Edit

Disabled

Use the disabled attribute to disable the checkbox.

<pc-checkbox disabled>Disabled</pc-checkbox>

Code

Edit

Sizes

Use the size attribute to change the checkbox’s size.

<pc-checkbox size="small">Small</pc-checkbox>
<br />
<pc-checkbox size="medium">Medium</pc-checkbox>
<br />
<pc-checkbox size="large">Large</pc-checkbox>

Code

Edit

Hint

Add a hint to a checkbox with the hint attribute. For hints that contain HTML, use the hint slot instead.

<pc-checkbox hint="What should the user know about the checkbox?">
    Label
</pc-checkbox>

Code

Edit

Custom validity

Use the setCustomValidity() method to set a custom validation message. This will prevent the form from submitting and make the browser display the error message you provide. To clear the error, call this function with an empty string.

<form class="custom-validity">
    <pc-checkbox>Check me</pc-checkbox>
    <br /><br />
    <pc-button appearance="primary" type="submit">Submit</pc-button>
</form>

<script>
    const form = document.querySelector(".custom-validity");
    const checkbox = form.querySelector("pc-checkbox");

    // Set initial validity as soon as the element is defined
    customElements.whenDefined("pc-checkbox").then(async () => {
        await checkbox.updateComplete;
        checkbox.setCustomValidity("Don’t forget to check me!");
    });

    checkbox.addEventListener("pc-change", () => {
        checkbox.setCustomValidity(checkbox.checked ? "" : "Don’t forget to check me!");
    });

    form.addEventListener("submit", (event) => {
        event.preventDefault();
        alert("All fields are valid!");
    });
</script>

Code

Edit

Properties

Name	Description	Default
`name`	The name of the checkbox, submitted as a name/value pair with form data. Type: `string`	`""`
`value`	The current value of the checkbox, submitted as a name/value pair with form data. Type: `string`	`""`
`size`	The checkbox’s size. Type: `"small" \| "medium" \| "large"`	`"medium"`
`disabled`	Disables the checkbox. Type: `boolean`	`false`
`checked`	Checks the checkbox off. Type: `boolean`	`false`
`indeterminate`	Sets the checkbox’s state to indeterminate. This is usually applied to checkboxes that represent a “Select all/none” behaviour when associated checkboxes have a mix of checked and unchecked states. Type: `boolean`	`false`
`defaultChecked`	The default value of the checkbox. Primarily used for resetting the checkbox. Type: `boolean`	`false`
`form`	By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you to place the form control outside of a form and associate it with the form that has this `id`. The form must be in the same document or shadow root for this to work. Type: `string`	`""`
`required`	Indicates that the checkbox must be checked. Type: `boolean`	`false`
`hint`	The checkbox’s hint. If you need to display HTML, use the `hint` slot instead. Type: `string`	`""`
`validity`	Gets the validity state object.	‐
`validationMessage`	Gets the validation message.	‐
`updateComplete`	A read‐only promise that resolves when the component has finished updating.	‐

Learn more about customising animations.

Slots

Name	Description
(default)	The checkbox’s label.
`hint`	Text that describes how to use the checkbox. Alternatively, you can use the `hint` attribute.

Learn more about using slots.

Methods

Name	Description	Arguments
`click()`	Simulates a click on the checkbox.	‐
`focus()`	Focuses the checkbox.	`options: FocusOptions`
`blur()`	Unfocuses the checkbox (i.e., blurs it).	‐
`checkValidity()`	Checks for validity but does not show a validation message. Returns `true` when valid and `false` when invalid.	‐
`getForm()`	Gets the associated form, if one exists.	‐
`reportValidity()`	Checks for validity and shows the browser’s validation message if the checkbox is invalid.	‐
`setCustomValidity()`	Sets a custom validation message. Pass an empty string to restore validity.	`message: string`

Learn more about methods.

Events

Name	Description	Event detail
`pc-input`	Emitted when the checkbox receives input.	‐
`pc-change`	Emitted when the checkbox’s state changes.	‐
`pc-focus`	Emitted when the checkbox gains focus.	‐
`pc-blur`	Emitted when the checkbox loses focus.	‐
`pc-invalid`	Emitted when the checkbox has been checked for validity and its constraints aren’t satisfied.	‐

Learn more about events.

Parts

Name	Description
`base`	The component’s base wrapper.
`control`	The container that wraps the checkbox’s state.
`checkbox-checked`	Matches the `control` part when the checkbox is checked.
`checkbox-indeterminate`	Matches the `control` part when the checkbox is indeterminate.
`icon-checked`	The checked icon, a `<pc-icon>` element.
`icon-indeterminate`	The indeterminate icon, a `<pc-icon>` element.
`label`	The container that wraps the checkbox’s label.
`hint`	The container that wraps the checkbox’s hint.

Learn more about customising CSS parts.

Importing

If you’re using the autoloader or the standard loader, you can skip this section. But if you’re cherry picking, you can use any of the following snippets to import this component.

CDN (script tag)

CDN (import)

npm (import)

To manually import this component from the CDN, copy this code snippet and paste it in your HTML.

  <script type="module" src="https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.3/cdn/components/checkbox/checkbox.js"></script> 

To manually import this component from the CDN, copy this code snippet and paste it in your JavaScript file.

  import "https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.3/cdn/components/checkbox/checkbox.js"; 

To manually import this component from npm, copy this code snippet and paste it in your JavaScript file.

import "placer-toolkit/dist/components/checkbox/checkbox.js";

Dependencies

This component automatically imports these components:

Icon