Checkbox

Select multiple independent items or confirm consent.

<sy-checkbox>Installation guide Basic usage

Live preview

Interact with the component to see results here.

View code

HTML

<sy-checkbox
  checked
  name="notifications"
  value="email"
  id="sample"
>Receive notification emails</sy-checkbox>

Usage guide

Use to toggle multiple independent items. Use Radio for one mutually exclusive value.

Write the error message in the error slot.
Inside the component, add <span slot="error">Error message</span>. You can include links and other guidance as well as text. For inputs supporting noNativeValidity, enable it to show this guidance instead of a browser popup. Switch always displays errors below the component.
Report business rule failures with setCustomError().
For example, if the server rejects a duplicate value, update the error slot and call setCustomError(). This method does not take a message argument. A custom error also blocks form submission.
Clear the error after resolving it and check whether submission is allowed.
Use clearCustomError() to clear a business rule error. Required-field and format validation remain active. await checkValidity() returns true or false; reportValidity() validates and displays errors. Read valid named values through FormData on submission.

Select and deselect

Manage selection with checked. Changing one item preserves other selections.

Indeterminate

indeterminate indicates that some child items are selected. Manage the actual checked value in your app.

Examples

Independent multiple selection

Toggle each item independently.

Ask AI

Stack these elements vertically. - sy-checkbox "Design" — name: "teams", value: "0", checked: true - sy-checkbox "Engineering" — name: "teams", value: "1" - sy-checkbox "Marketing" — name: "teams", value: "2"

View code

HTML

<div style="display:grid;gap:16px;width:100%">
  <sy-checkbox
    name="teams"
    value="0"
    checked
  >Design</sy-checkbox>
  <sy-checkbox name="teams" value="1">Engineering</sy-checkbox>
  <sy-checkbox name="teams" value="2">Marketing</sy-checkbox>
</div>

Indeterminate state

Indicate that some items are selected. Clicking lets the user make an explicit selection.

Ask AI

Create the following component. - sy-checkbox "Select all" — indeterminate: true

View code

HTML

<sy-checkbox indeterminate>Select all</sy-checkbox>

Disabled and read only

From top to bottom: default, disabled, and read only. Disabled fields cannot receive focus or input. Read-only fields keep their value but prevent editing.

Ask AI

Stack these elements vertically. - sy-checkbox "Email notifications" — checked: true - sy-checkbox "Email notifications" — checked: true, disabled: true - sy-checkbox "Email notifications" — checked: true, readonly: true

View code

HTML

<div style="display:grid;gap:16px;width:100%">
  <sy-checkbox checked>Email notifications</sy-checkbox>
  <sy-checkbox checked disabled>Email notifications</sy-checkbox>
  <sy-checkbox checked readonly>Email notifications</sy-checkbox>
</div>

Events and payloads

Interact with the component and inspect the latest event name and detail. The code includes subscriptions to events emitted by this component and its children.

Ask AI

Create the following component. - sy-checkbox "Receive notification emails" — checked: true, name: "notifications", value: "email" Show the latest events: changed, focused, blured

View code

HTML

<sy-checkbox
  checked
  name="notifications"
  value="email"
  id="sample"
>Receive notification emails</sy-checkbox>
<output id="demo-events" aria-live="polite">Interact with the component to see
  its latest event and payload.</output>

<script type="module">
  const describeResult = value => JSON.stringify(value, (_key, item) => {
    if (item instanceof File) return {
      name: item.name,
      size: item.size,
      type: item.type
    };
    if (item instanceof Element) return `<${item.localName}>`;
    return item;
  }) ?? 'Done';
  for (const name of ["changed", "focused", "blured"]) {
    document.addEventListener(name, event => {
      document.querySelector('#demo-events').textContent =
        `${event.target.localName} · ${name}: ${describeResult(event.detail)}`;
    });
  }
</script>

Checkbox helper text

checkboxTitle is passed to the internal checkbox's title. Put visible text in the default slot and additional information in title.

Ask AI

Create the following component. - sy-checkbox "Receive notification emails" — checked: true, title: "Receive project updates by email.", name: "notifications", value: "email" - JS property checkboxTitle: "Receive project updates by email."

View code

HTML

<sy-checkbox
  checked
  title="Receive project updates by email."
  name="notifications"
  value="email"
  id="sample"
>Receive notification emails</sy-checkbox>

<script type="module">
  const component1 = document.querySelector("#sample");
  Object.assign(component1, {
    "checkboxTitle": "Receive project updates by email."
  });
</script>

Forms and validation

Submit an empty value to trigger required-field validation. Enter a value and submit to inspect the form data, then try enabling and clearing a custom error.

Ask AI

Create the following component. Place the content in a form. - sy-checkbox "I agree to the terms." — name: "field", required: true, value: "accepted" - span "Agreement is required." (error slot) Keep each element's quoted label, including the parent's label when it has slot children.

View code

HTML

<form style="display:grid;gap:16px">
  <sy-checkbox
    name="field"
    required
    value="accepted"
    id="sample"
  >I agree to the terms.<span slot="error">Agreement is required.</span>
  </sy-checkbox>
  <div style="display:flex;flex-wrap:wrap;gap:8px">
    <sy-button type="submit" variant="primary">Submit</sy-button>
    <sy-button type="reset">Reset</sy-button>
  </div>
</form>
<div class="demo-actions"
  style="display:flex;flex-wrap:wrap;gap:8px;margin-top:16px"
>
  <sy-button id="action-0" size="small">Check validity</sy-button>
  <sy-button id="action-1" size="small">Show error</sy-button>
  <sy-button id="action-2" size="small">Clear error</sy-button>
</div>
<output id="demo-result" aria-live="polite"></output>

<script type="module">
  const describeResult = value => JSON.stringify(value, (_key, item) => {
    if (item instanceof File) return {
      name: item.name,
      size: item.size,
      type: item.type
    };
    if (item instanceof Element) return `<${item.localName}>`;
    return item;
  }) ?? 'Done';
  const actionTarget0 = document.querySelector("#sample");
  document.querySelector('#action-0').addEventListener('click', async () => {
    const result = await actionTarget0.checkValidity();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget1 = document.querySelector("#sample");
  document.querySelector('#action-1').addEventListener('click', async () => {
    const result = await actionTarget1.setCustomError();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget2 = document.querySelector("#sample");
  document.querySelector('#action-2').addEventListener('click', async () => {
    const result = await actionTarget2.clearCustomError();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  document.querySelector('form').addEventListener('submit', event => {
    event.preventDefault();
    document.querySelector('#demo-result').textContent = describeResult([...new FormData(event
      .currentTarget)]);
  });
</script>

Read validation results and error states

Validate before submitting or display errors on screen. Check an empty required field, then fill it to see how the return value changes. Querying the state distinguishes custom errors from required-field errors.

Ask AI

View code

HTML

<form style="display:grid;gap:16px">
  <sy-checkbox
    name="field"
    required
    value="accepted"
    id="sample"
  >I agree to the terms.<span slot="error">Agreement is required.</span>
  </sy-checkbox>
  <div style="display:flex;flex-wrap:wrap;gap:8px">
    <sy-button type="submit" variant="primary">Submit</sy-button>
    <sy-button type="reset">Reset</sy-button>
  </div>
</form>
<div class="demo-actions"
  style="display:flex;flex-wrap:wrap;gap:8px;margin-top:16px"
>
  <sy-button id="action-0" size="small">Check validity</sy-button>
  <sy-button id="action-1" size="small">Show error</sy-button>
  <sy-button id="action-2" size="small">Clear error</sy-button>
  <sy-button id="action-3" size="small">Validate with errors</sy-button>
  <sy-button id="action-4" size="small">Query validation state</sy-button>
</div>
<output id="demo-result" aria-live="polite"></output>

<script type="module">
  const describeResult = value => JSON.stringify(value, (_key, item) => {
    if (item instanceof File) return {
      name: item.name,
      size: item.size,
      type: item.type
    };
    if (item instanceof Element) return `<${item.localName}>`;
    return item;
  }) ?? 'Done';
  const actionTarget0 = document.querySelector("#sample");
  document.querySelector('#action-0').addEventListener('click', async () => {
    const result = await actionTarget0.checkValidity();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget1 = document.querySelector("#sample");
  document.querySelector('#action-1').addEventListener('click', async () => {
    const result = await actionTarget1.setCustomError();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget2 = document.querySelector("#sample");
  document.querySelector('#action-2').addEventListener('click', async () => {
    const result = await actionTarget2.clearCustomError();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget3 = document.querySelector("#sample");
  document.querySelector('#action-3').addEventListener('click', async () => {
    const result = await actionTarget3.reportValidity();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget4 = document.querySelector("#sample");
  document.querySelector('#action-4').addEventListener('click', async () => {
    const result = await actionTarget4.getValidStatus();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  document.querySelector('form').addEventListener('submit', event => {
    event.preventDefault();
    document.querySelector('#demo-result').textContent = describeResult([...new FormData(event
      .currentTarget)]);
  });
</script>

Custom error messages

Display a custom error for server-side duplicate checks or business rules. Change the message below and submit to verify that it is blocked. After clearing the error, required-field constraints must still be satisfied.

View code

HTML

<label for="error-message">Error message to display</label><input
  id="error-message"
  value="The server did not accept this value. Please review it."
  type="text"
>
<form style="display:grid;gap:16px">
  <sy-checkbox
    no-native-validity
    name="field"
    required
    value="accepted"
    id="sample"
  >I agree to the terms.<span slot="error">Agreement is required.</span>
  </sy-checkbox>
  <div style="display:flex;flex-wrap:wrap;gap:8px">
    <sy-button type="submit" variant="primary">Submit</sy-button>
    <sy-button type="reset">Reset</sy-button>
  </div>
</form>
<div class="demo-actions">
  <sy-button id="show-custom-error" variant="primary">Show error</sy-button>
  <sy-button id="clear-custom-error">Clear error</sy-button>
</div>
<output id="custom-error-result" aria-live="polite"></output>
<output id="demo-result" aria-live="polite"></output>

<script type="module">
  const describeResult = value => JSON.stringify(value, (_key, item) => {
    if (item instanceof File) return {
      name: item.name,
      size: item.size,
      type: item.type
    };
    if (item instanceof Element) return `<${item.localName}>`;
    return item;
  }) ?? 'Done';
  await (async function customErrorSetup(root) {
    const field = root.querySelector('#sample');
    const message = root.querySelector('[slot="error"]');
    const input = root.querySelector('#error-message');
    const output = root.querySelector('#custom-error-result');
    const update = async () => {
      message.textContent = input.value.trim() || _msg("m_4eea8cef81c6");
      await field.setCustomError();
      output.textContent = _msg("m_e00bd46236d3", [message.textContent]);
    };
    input.addEventListener('input', update);
    root.querySelector('#show-custom-error').addEventListener('click', update);
    root.querySelector('#clear-custom-error').addEventListener('click', async () => {
      await field.clearCustomError();
      output.textContent = await field.checkValidity() ? _msg("m_c454251167b2") : _msg(
        "m_5b8cb48627e5");
    });
    root.querySelector('form').addEventListener('invalid', () => {
      output.textContent = _msg("m_c702c7778166");
    }, true);
    root.querySelector('form').addEventListener('reset', () => {
      output.textContent = _msg("m_b90c2b4dc30f");
    });
    await update();
  })(document);
  document.querySelector('form').addEventListener('submit', event => {
    event.preventDefault();
    document.querySelector('#demo-result').textContent = describeResult([...new FormData(event
      .currentTarget)]);
  });
</script>

Feature examples

Choose a feature from 10 topics. Explore property settings, method calls, event results, and slot layouts through live examples and code.

Find a feature

Usage examples · Overview

Try the selected example. Topics with multiple configurations let you switch between detailed examples.

View code

HTML

Loading the example.