Checkbox

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

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

Code

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

Indeterminate

Use the indeterminate attribute to make the checkbox indeterminate.

<pc-checkbox indeterminate>Indeterminate</pc-checkbox>

Code

Disabled

Use the disabled attribute to disable the checkbox.

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

Code

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

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

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

Properties

Name	Description	Default
`dependencies`	`object`	`{ "pc-icon": PcIcon }`
`input`	`HTMLInputElement`	-
`checked`	`boolean`	`false`
`defaultChecked`	`boolean`	`false`
`disabled`	`boolean`	`false`
`form`	`string`	`""`
`hint`	`string`	`""`
`indeterminate`	`boolean`	`false`
`invalid`	`boolean`	`false`
`name`	`string`	`""`
`pressed`	`boolean`	`false`
`required`	`boolean`	`false`
`size`	`"small" \| "medium" \| "large"`	`"medium"`
`title`	`string`	`""`
`value`	`string`	`""`
`validity`		-
`validationMessage`		-
`updateComplete`	A read‐only promise that resolves when the component has finished updating.	-

Learn more about attributes and properties.

Methods

Name	Description	Arguments
`handleDisabledChange()`		-
`handleStateChange()`		-
`click()`		-
`focus()`		`options: FocusOptions`
`blur()`		-
`checkValidity()`		-
`getForm()`		-
`reportValidity()`		-
`setCustomValidity()`		`message: string`

Learn more about methods.

Importing

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

Script

Import

Bundler

To import this component from the CDN with a script tag, copy this snippet and paste it in your HTML.

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

To import this component from the CDN using a JavaScript import, copy this snippet and paste it in your JavaScript:

import "https://cdn.jsdelivr.net/npm/placer-toolkit@0.5.1/dist/components/checkbox/checkbox.js";

To import this component with a bundler using a JavaScript import, copy this snippet and paste it in your JavaScript:

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