Porsche Design System

Checkbox

Table of Contents

Indeterminate
Form
Controlled
Slots

Indeterminate#

Mask the visual appearance of a checkbox which has a state in-between checked and unchecked. This is especially useful for a checkbox that is used to set the state of a group of checkboxes at once. However, this group might have a mixed state. In this case we recommend to use checked=false and indeterminate=true.

Note: The indeterminate attribute only affects how the checkbox is shown. The current value is hidden from the user, but the checkbox still keeps it's checked state. You can find more details in the specification.

Open in Stackblitz

<!doctype html>
<html lang="en" class="auto">
<head>
  <title></title>
</head>
<body class="bg-base">

<p-checkbox label="Some label" indeterminate="true"></p-checkbox>

<p-checkbox label="Some label" indeterminate="true" checked="true"></p-checkbox>
<script>

</script>
</body>
</html>

Form#

The p-checkbox component is a form-associated custom element that integrates seamlessly with forms. Leveraging the ElementInternals API, it functions like a native checkbox, ensuring compatibility with form behaviors. However, note that browser support for this API is limited.

Last submitted data:

Open in Stackblitz

<!doctype html>
<html lang="en" class="auto">
<head>
  <title></title>
</head>
<body class="bg-base">

<form>
  <p-checkbox name="some-name" label="Some Label" value="some-label"></p-checkbox>
  <p-button type="submit">Submit</p-button>
  <p-button type="reset">Reset</p-button>
</form>

<p-text>Last submitted data: </p-text>
<script>
  const debugElement = document.querySelector('p-text');
  const form = document.querySelector('form');
  form.addEventListener('submit', (e) => {
    e.preventDefault();
    const formData = new FormData(form);
    debugElement.innerText = `Last submitted data: ${formData.get('some-name') ?? ''}`;
  });
</script>
</body>
</html>

Controlled#

In the controlled approach, the p-checkbox checked state is externally managed. While the internal checked state will be updated automatically, you can use the update or blur event to update the external state.

some-name: true

Open in Stackblitz

<!doctype html>
<html lang="en" class="auto">
<head>
  <title></title>
</head>
<body class="bg-base">

<p-checkbox name="some-name" label="Some Label" value="some-value" checked></p-checkbox>

<p-text>some-name: true</p-text>
<script>
  const debugElement = document.querySelector('p-text');
  const checkbox = document.querySelector('p-checkbox');

  checkbox.addEventListener('update', (e) => {
    setDebugText(e.detail.checked);
  });

  function setDebugText(value) {
    debugElement.innerText = `some-name: ${value}`;
  }
</script>
</body>
</html>

Slots#

Sometimes it's useful to be able to render markup (e.g. an anchor tag) for label or message. Therefore, a named slot can be used. Make sure not to define the corresponding property on the host element when a named slot is used (because a property definition is preferred over a named slot). For named slots only phrasing content is allowed.

Some label with a linkSome error message with a link

Open in Stackblitz

<!doctype html>
<html lang="en" class="auto">
<head>
  <title></title>
</head>
<body class="bg-base">

<p-checkbox state="error" name="some-name" aria-labelledby="some-label-id" aria-describedby="some-message-id">
  <span slot="label" id="some-label-id">
    Some label with a 
    <a href="https://designsystem.porsche.com">
      link
    </a>
  </span>
  <span slot="message" id="some-message-id">
    Some error message with a 
    <a href="https://designsystem.porsche.com">
      link
    </a>
  </span>
</p-checkbox>
<script>

</script>
</body>
</html>