Skip to main content
Light Dark System

Checkbox

<zn-checkbox> | ZnCheckbox
Since 1.0 experimental

Short summary of the component’s intended use.

Accept terms and conditions
<zn-checkbox>Accept terms and conditions</zn-checkbox>

Examples

Basic Checkbox

A basic checkbox with a label.

Financial products access
<zn-checkbox>Financial products access</zn-checkbox>

Checked

Use the checked attribute to activate the checkbox by default.

I agree to the terms
<zn-checkbox checked>I agree to the terms</zn-checkbox>

Indeterminate

Use the indeterminate attribute to show an indeterminate state. This is typically used to represent a “select all” checkbox when some but not all items are selected.

Select all items
<zn-checkbox indeterminate>Select all items</zn-checkbox>

Disabled

Use the disabled attribute to disable the checkbox.

Disabled checkbox
Disabled and checked
<zn-checkbox disabled>Disabled checkbox</zn-checkbox>
<br />
<zn-checkbox disabled checked>Disabled and checked</zn-checkbox>

Sizes

Use the size attribute to change the checkbox size. Available sizes are small, medium (default), and large.

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

Colors

Use the color attribute to apply semantic colors to the checkbox. When checked or indeterminate, the checkbox will use the specified color.

Default
Primary
Secondary
Info
Success
Warning
Error
<zn-checkbox color="default" checked>Default</zn-checkbox>
<br />
<zn-checkbox color="primary" checked>Primary</zn-checkbox>
<br />
<zn-checkbox color="secondary" checked>Secondary</zn-checkbox>
<br />
<zn-checkbox color="info" checked>Info</zn-checkbox>
<br />
<zn-checkbox color="success" checked>Success</zn-checkbox>
<br />
<zn-checkbox color="warning" checked>Warning</zn-checkbox>
<br />
<zn-checkbox color="error" checked>Error</zn-checkbox>

Checked and Unchecked Colors

Use the checked-color and unchecked-color attributes to apply different colors based on the checkbox state.

Checked color (success)
Unchecked color (error)
<zn-checkbox checked-color="success" unchecked-color="error" checked>Checked color (success)</zn-checkbox>
<br />
<zn-checkbox checked-color="success" unchecked-color="error">Unchecked color (error)</zn-checkbox>

Description

Add descriptive help text to checkboxes with the description attribute. For descriptions that contain HTML, use the description slot instead.

Financial products access

Advanced settings
This option enables advanced features that require additional permissions.
<zn-checkbox description="Grants access to cash account and charge card features">Financial products access</zn-checkbox>
<br /><br />
<zn-checkbox>
  Advanced settings
  <div slot="description">
    This option enables <strong>advanced features</strong> that require additional permissions.
  </div>
</zn-checkbox>

Label and Label Tooltip

Use the label attribute to add a form control label above the checkbox. Use label-tooltip to provide additional context.

Enable notifications
<zn-checkbox label="User Preferences" label-tooltip="Configure your account settings">
  Enable notifications
</zn-checkbox>

Custom Icons

Use the checked-icon and unchecked-icon attributes to display custom icons for different states.

Add to favorites
Like this
<zn-checkbox checked-icon="favorite" color="error" checked>Add to favorites</zn-checkbox>
<br />
<zn-checkbox checked-icon="thumb_up" unchecked-icon="thumb_down" color="success">Like this</zn-checkbox>

Contained Style

Add the contained attribute to draw a card-like container around a checkbox. This style is useful for giving more emphasis to a checkbox or list of checkboxes.

Financial products access

Initiate outbound transfers Approve outbound transfers Export transactions
<zn-checkbox description="Grants access to cash account and charge card features" contained>Financial products access</zn-checkbox>
<br/><br/>
<zn-checkbox-group label="Financial products permissions" contained>
  <zn-checkbox description="Requires separate initiators and approvers">Initiate outbound transfers</zn-checkbox>
  <zn-checkbox description="Requires separate initiators and approvers">Approve outbound transfers</zn-checkbox>
  <zn-checkbox description="Applies to both cash account and charge card" disabled>Export transactions</zn-checkbox>
</zn-checkbox-group>

Borderless

Use the borderless attribute to remove borders from the checkbox.

Borderless checkbox
Borderless checked
<zn-checkbox borderless>Borderless checkbox</zn-checkbox>
<br />
<zn-checkbox borderless checked>Borderless checked</zn-checkbox>

Horizontal Layout

Use the horizontal attribute to apply styles relevant to checkboxes in a horizontal layout. This is typically used with checkbox groups.

Option 1 Option 2 Option 3
<div style="display: flex; gap: 1rem;">
  <zn-checkbox horizontal>Option 1</zn-checkbox>
  <zn-checkbox horizontal>Option 2</zn-checkbox>
  <zn-checkbox horizontal>Option 3</zn-checkbox>
</div>

Selected Content

Use the selected-content slot to display additional content (such as an input field) inside a contained checkbox when it is checked. The slot is unstyled by default. Use ::part(selected-content) to style the content as needed.

Grant financial products access

A mobile number is required to grant this user access to financial products. The number will be used for login verification.

<zn-checkbox style="width:100%" contained>Grant financial products access
  <div slot="selected-content">
    <p>A mobile number is required to grant this user access to financial products. The number will be used for login verification.</p>
    <zn-input style="width: 280px;" label="Mobile number" type="tel" required optional-icon></zn-input>
  </div>
</zn-checkbox>
<style>
  zn-checkbox::part(selected-content) {
    font-size: 14px;
    font-weight: normal;
    color: #6D7176;
    margin-top: 1rem;
  }
</style>

Form Integration

Checkboxes work seamlessly with forms and will be submitted with form data.

Subscribe to newsletter
I accept the terms and conditions

Submit Reset
<form id="checkbox-form">
  <zn-checkbox name="newsletter" value="yes">Subscribe to newsletter</zn-checkbox>
  <br />
  <zn-checkbox name="terms" value="accepted" required>I accept the terms and conditions</zn-checkbox>
  <br /><br />
  <zn-button type="submit" color="primary">Submit</zn-button>
  <zn-button type="reset" color="secondary">Reset</zn-button>
</form>

<script type="module">
  const form = document.querySelector('#checkbox-form');
  form.addEventListener('submit', (event) => {
    event.preventDefault();
    const formData = new FormData(form);
    const data = Object.fromEntries(formData.entries());
    alert('Form submitted: ' + JSON.stringify(data, null, 2));
  });
</script>

Unchecked Value

Use the unchecked-value attribute to submit a specific value when the checkbox is unchecked.

Receive email updates

Submit
<form id="unchecked-value-form">
  <zn-checkbox name="receive-emails" value="yes" unchecked-value="no" checked>
    Receive email updates
  </zn-checkbox>
  <br /><br />
  <zn-button type="submit" color="primary">Submit</zn-button>
</form>

<script type="module">
  const form = document.querySelector('#unchecked-value-form');
  form.addEventListener('submit', (event) => {
    event.preventDefault();
    const formData = new FormData(form);
    alert('Value: ' + formData.get('receive-emails'));
  });
</script>

Required Validation

Use the required attribute to make the checkbox required. The form will not submit unless the checkbox is checked.

I agree to the terms and conditions

Submit
<form id="required-form">
  <zn-checkbox name="agree" required>
    I agree to the terms and conditions
  </zn-checkbox>
  <br /><br />
  <zn-button type="submit" color="primary">Submit</zn-button>
</form>

<script type="module">
  const form = document.querySelector('#required-form');
  form.addEventListener('submit', (event) => {
    event.preventDefault();
    alert('Form is valid!');
  });
</script>

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.

I understand the risks involved
Submit
<form class="custom-validity">
  <zn-checkbox>I understand the risks involved</zn-checkbox>
  <br/>
  <zn-button type="submit" color="primary" style="margin-top: 1rem;">Submit</zn-button>
</form>
<script type="module">
  const form = document.querySelector('.custom-validity');
  const checkbox = form.querySelector('zn-checkbox');
  const errorMessage = `You must acknowledge the risks before proceeding`;

  // Set initial validity as soon as the element is defined
  customElements.whenDefined('zn-checkbox').then(async () => {
    await checkbox.updateComplete;
    checkbox.setCustomValidity(errorMessage);
  });

  // Update validity on change
  checkbox.addEventListener('zn-change', () => {
    checkbox.setCustomValidity(checkbox.checked ? '' : errorMessage);
  });

  // Wait for controls to be defined before attaching form listeners
  await Promise.all([
    customElements.whenDefined('zn-checkbox')
  ]).then(() => {
    form.addEventListener('submit', event => {
      event.preventDefault();
      alert('All fields are valid!');
    });
  });
</script>

Submit on Click

Use the submit-on-click attribute to automatically submit the containing form when the checkbox is clicked.

Apply changes immediately
<form id="submit-on-click-form">
  <zn-checkbox name="instant" submit-on-click>
    Apply changes immediately
  </zn-checkbox>
</form>

<script type="module">
  const form = document.querySelector('#submit-on-click-form');
  let submitCount = 0;
  form.addEventListener('submit', (event) => {
    event.preventDefault();
    submitCount++;
    alert('Form submitted ' + submitCount + ' time(s)');
  });
</script>

External Form Association

Use the form attribute to associate the checkbox with a form element by ID, even if the checkbox is not a descendant of the form.

Submit External Form


This checkbox is associated with the form above
<form id="external-form">
  <zn-button type="submit" color="primary">Submit External Form</zn-button>
</form>

<br /><br />

<zn-checkbox form="external-form" name="external-option" value="selected">
  This checkbox is associated with the form above
</zn-checkbox>

<script type="module">
  const form = document.querySelector('#external-form');
  form.addEventListener('submit', (event) => {
    event.preventDefault();
    const formData = new FormData(form);
    alert('External option: ' + (formData.get('external-option') || 'not selected'));
  });
</script>

Events

Checkboxes emit several events that you can listen to:

  • zn-change - Emitted when the checked state changes
  • zn-input - Emitted when the checkbox receives input
  • zn-focus - Emitted when the checkbox gains focus
  • zn-blur - Emitted when the checkbox loses focus
  • zn-invalid - Emitted when form validation fails
Toggle me
Events:
    <div>
      <zn-checkbox id="event-checkbox">Toggle me</zn-checkbox>
      <div id="event-output" style="margin-top: 1rem; padding: 1rem; background: #f5f5f5; border-radius: 4px;">
        <strong>Events:</strong>
        <ul id="event-list" style="margin: 0.5rem 0 0 0; padding-left: 1.5rem;"></ul>
      </div>
    </div>
    
    <script type="module">
      const checkbox = document.querySelector('#event-checkbox');
      const eventList = document.querySelector('#event-list');
    
      function logEvent(eventName, detail = '') {
        const li = document.createElement('li');
        li.textContent = `${eventName}${detail ? ': ' + detail : ''}`;
        eventList.insertBefore(li, eventList.firstChild);
    
        // Keep only last 5 events
        while (eventList.children.length > 5) {
          eventList.removeChild(eventList.lastChild);
        }
      }
    
      checkbox.addEventListener('zn-change', (e) => {
        logEvent('zn-change', `checked = ${e.target.checked}`);
      });
    
      checkbox.addEventListener('zn-input', () => {
        logEvent('zn-input');
      });
    
      checkbox.addEventListener('zn-focus', () => {
        logEvent('zn-focus');
      });
    
      checkbox.addEventListener('zn-blur', () => {
        logEvent('zn-blur');
      });
    </script>
    

    Methods

    Checkboxes provide several methods for programmatic control:

    • click() - Simulates a click on the checkbox
    • focus() - Sets focus on the checkbox
    • blur() - Removes focus from the checkbox
    • checkValidity() - Checks validity without showing a message
    • reportValidity() - Checks validity and shows the browser’s validation message
    • setCustomValidity(message) - Sets a custom validation message
    Programmatic control

    Click Checkbox Focus Checkbox Blur Checkbox Check Validity
    <div>
      <zn-checkbox id="method-checkbox">Programmatic control</zn-checkbox>
      <br /><br />
      <zn-button id="click-btn" size="small">Click Checkbox</zn-button>
      <zn-button id="focus-btn" size="small" color="info">Focus Checkbox</zn-button>
      <zn-button id="blur-btn" size="small" color="secondary">Blur Checkbox</zn-button>
      <zn-button id="validate-btn" size="small" color="warning">Check Validity</zn-button>
    </div>
    
    <script type="module">
      const checkbox = document.querySelector('#method-checkbox');
    
      document.querySelector('#click-btn').addEventListener('click', () => {
        checkbox.click();
      });
    
      document.querySelector('#focus-btn').addEventListener('click', () => {
        checkbox.focus();
      });
    
      document.querySelector('#blur-btn').addEventListener('click', () => {
        checkbox.blur();
      });
    
      document.querySelector('#validate-btn').addEventListener('click', () => {
        const isValid = checkbox.checkValidity();
        alert('Checkbox is ' + (isValid ? 'valid' : 'invalid'));
      });
    </script>
    

    Importing

    If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

    To import this component from the CDN using a script tag:

    <script type="module" src="https://cdn.jsdelivr.net/npm/@kubex/zinc@1.0.66/dist/components/checkbox/checkbox.js"></script>

    To import this component from the CDN using a JavaScript import:

    import 'https://cdn.jsdelivr.net/npm/@kubex/zinc@1.0.66/dist/components/checkbox/checkbox.js';

    To import this component using a bundler:

    import '@kubex/zinc/dist/components/checkbox/checkbox.js';

    Slots

    Name Description
    (default) The checkbox’s label.
    description A description of the checkbox’s label. Serves as help text for a checkbox item. Alternatively, you can use the description attribute.
    selected-content Use to nest rich content (like an input) inside a selected checkbox item. Use only with the contained style.

    Learn more about using slots.

    Properties

    Name Description Reflects Type Default
    name The name of the checkbox, submitted as a name/value pair with form data. string ''
    value The current value of the checkbox, submitted as a name/value pair with form data. string -
    uncheckedValue
    unchecked-value
    The unchecked value of the checkbox, submitted as a name/value pair with form data. string -
    size The checkbox’s size. 'small' | 'medium' | 'large' 'medium'
    disabled Disables the checkbox. boolean false
    checked Draws the checkbox in a checked state. boolean false
    indeterminate Draws the checkbox in an indeterminate state. This is usually applied to checkboxes that represents a “select all/none” behavior when associated checkboxes have a mix of checked and unchecked states. boolean false
    contained Draws a container around the checkbox. boolean false
    borderless Removes a container around the checkbox. boolean false
    horizontal Applies styles relevant to checkboxes in a horizontal layout. boolean false
    defaultChecked The default value of the form control. Primarily used for resetting the form control. 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. string ''
    required Makes the checkbox a required field. boolean false
    submitOnClick
    submit-on-click
    Submits the form when checkbox is clicked. boolean false
    description The checkbox’s help text. If you need to display HTML, use the description slot instead. string ''
    checkedIcon
    checked-icon
    The icon to show when the checkbox is checked. string ''
    uncheckedIcon
    unchecked-icon
    The icon to show when the checkbox is unchecked. string ''
    color The color of the checkbox. ColorOption 'default'
    checkedColor
    checked-color
    The color of the checkbox when checked. Overrides color. ColorOption -
    uncheckedColor
    unchecked-color
    The color of the checkbox when unchecked. Overrides color. ColorOption -
    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 attributes and properties.

    Events

    Name React Event Description Event Detail
    zn-blur Emitted when the checkbox loses focus. -
    zn-change Emitted when the checked state changes. -
    zn-focus Emitted when the checkbox gains focus. -
    zn-input Emitted when the checkbox receives input. -
    zn-invalid Emitted when the form control has been checked for validity and its constraints aren’t satisfied. -

    Learn more about events.

    Methods

    Name Description Arguments
    click() Simulates a click on the checkbox. -
    focus() Sets focus on the checkbox. options: FocusOptions
    blur() Removes focus from the checkbox. -
    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 control is invalid. -
    setCustomValidity() Sets a custom validation message. The value provided will be shown to the user when the form is submitted. To clear the custom validation message, call this method with an empty string. message: string

    Learn more about methods.

    Parts

    Name Description
    base The component’s base wrapper.
    control The square container that wraps the checkbox’s checked state.
    control--checked Matches the control part when the checkbox is checked.
    control--indeterminate Matches the control part when the checkbox is indeterminate.
    checked-icon The checked icon, an <zn-icon> element.
    unchecked-icon The unchecked icon, an <zn-icon> element.
    indeterminate-icon The indeterminate icon, an <zn-icon> element.
    label The container that wraps the checkbox’s label.
    description The container that wraps the checkbox’s description.
    selected-content The container that wraps optional content that appears when a checkbox is checked.

    Learn more about customizing CSS parts.

    Dependencies

    This component automatically imports the following dependencies.

    • <zn-example>
    • <zn-icon>