- Checkbox
- Examples
- Basic Checkbox
- Checked
- Indeterminate
- Disabled
- Sizes
- Colors
- Checked and Unchecked Colors
- Description
- Label and Label Tooltip
- Custom Icons
- Contained Style
- Borderless
- Horizontal Layout
- Selected Content
- Form Integration
- Unchecked Value
- Required Validation
- Custom Validity
- Submit on Click
- External Form Association
- Events
- Methods
- Importing
- Slots
- Properties
- Events
- Methods
- Parts
- Dependencies
Checkbox
<zn-checkbox> | ZnCheckbox
Short summary of the component’s intended use.
<zn-checkbox>Accept terms and conditions</zn-checkbox>
This component works with standard <form> elements. Please refer to the section on
form controls to learn more about form submission and
client-side validation.
Examples
Basic Checkbox
A basic checkbox with a label.
<zn-checkbox>Financial products access</zn-checkbox>
Checked
Use the checked attribute to activate the checkbox by default.
<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.
<zn-checkbox indeterminate>Select all items</zn-checkbox>
Disabled
Use the disabled attribute to disable the checkbox.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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>
When checkboxes are wrapped with Checkbox Group, adding the
contained attribute to the parent Checkbox Group or to any checkbox in the group
will create contained checkboxes for the entire group.
Borderless
Use the borderless attribute to remove borders from the checkbox.
<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.
<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.
Note: ts_form_for doesn’t support slots. The
selected-content slot cannot be used for checkboxes rendered with ts_form_for.
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.
<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.
<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.
<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.
<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.
<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.
<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 changeszn-input- Emitted when the checkbox receives inputzn-focus- Emitted when the checkbox gains focuszn-blur- Emitted when the checkbox loses focuszn-invalid- Emitted when form validation fails
<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 checkboxfocus()- Sets focus on the checkboxblur()- Removes focus from the checkboxcheckValidity()- Checks validity without showing a messagereportValidity()- Checks validity and shows the browser’s validation messagesetCustomValidity(message)- Sets a custom validation message
<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>