Checkbox

<pc-checkbox>

0.1.0

experimental

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

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

Eigenschaften

Name	Beschreibung	Standard
`name`	The name of the checkbox, submitted as a name/value pair with form data. Typ: `string`	`""`
`value`	The current value of the checkbox, submitted as a name/value pair with form data. Typ: `string`	`""`
`size`	The checkbox’s size. Typ: `"small" \| "medium" \| "large"`	`"medium"`
`disabled`	Disables the checkbox. Typ: `boolean`	`false`
`checked`	Checks the checkbox off. Typ: `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. Typ: `boolean`	`false`
`defaultChecked`	The default value of the checkbox. Primarily used for resetting the checkbox. Typ: `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. Typ: `string`	`""`
`required`	Indicates that the checkbox must be checked. Typ: `boolean`	`false`
`hint`	The checkbox’s hint. If you need to display HTML, use the `hint` slot instead. Typ: `string`	`""`
`validity`	Gets the validity state object.	‐
`validationMessage`	Gets the validation message.	‐
`updateComplete`	Ein schreibgeschütztes Promise, das erfüllt ist, sobald die Komponente fertig aktualisiert wurde.	‐

Erfahre mehr über Attribute und Eigenschaften.

Slots

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

Erfahre mehr über die Benutzung von Slots.

Methoden

Name	Beschreibung	Argumente
`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`

Erfahre mehr über Methoden.

Events

Name	Beschreibung	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.	‐

Erfahre mehr über Events.

Parts

Name	Beschreibung
`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.

Erfahre mehr über das Anpassen von CSS‐Parts.

Importieren

Wenn du den Autoloader oder den Standard‐Loader nutzt, kannst du diesen Abschnitt überspringen. Falls du „Cherry Picking“ betreibst, kannst du die folgenden Snippets verwenden, um diese Komponente zu importieren.

CDN (Skript‐Tag)

CDN (Import)

npm (Import)

Um diese Komponente manuell vom CDN zu importieren, kannst du dieses Code‐Snippet kopieren und es in dein HTML einfügen.

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

Um diese Komponente manuell vom CDN zu importieren, kannst du dieses Code‐Snippet kopieren und es in deine JavaScript‐Datei einfügen.

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

Um diese Komponente manuell von npm zu importieren, kannst du dieses Code‐Snippet kopieren und es in deine JavaScript‐Datei einfügen.

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

Abhängigkeiten

Diese Komponente importiert automatisch folgende Komponenten:

Icon