- Checkbox
- Examples
- Basic Checkbox
- Checked
- Indeterminate
- Disabled
- Sizes
- Colors
- Checked and Unchecked Colors
- Description
- Label and Label Tooltip
- Custom Icons
- Contained Style
- Multi-select Cards
- 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
- Custom Properties
- 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.
Multi-select Cards
Contained checkboxes support the same card content and placement options as
contained radios, while preserving checkbox semantics. Use
them inside zn-checkbox-group when people may select more than one card.
Set the title with card-title (or use the default slot), supporting text with
description, and an image with src and image-alt or the
image slot. image-position accepts top, right,
bottom, and left. Cards are rounded by default; add square to the
group to square off every card.
<zn-checkbox-group label="Choose benefits" help-text="Select all that apply" name="benefits" contained horizontal> <zn-checkbox value="health" card-title="Health insurance" description="Medical and dental cover." image-position="top" control-position="top-right"> <zn-icon slot="image" src="health_and_safety" size="64"></zn-icon> </zn-checkbox> <zn-checkbox value="pension" card-title="Pension" description="Employer contribution matching." image-position="top" control-position="top-right"> <zn-icon slot="image" src="savings" size="64"></zn-icon> </zn-checkbox> </zn-checkbox-group>
Image and control placement is identical for radio and checkbox cards. See the image and indicator position examples for a visual matrix of the four image directions, indicator corners, centered edge positions, and a hidden indicator.
control-position accepts top-left, top-center,
top-right, center-left, center, center-right,
bottom-left, bottom-center, and bottom-right. The default
start position retains the standard inline checkbox; use none to hide the
indicator so the card itself shows the selected state, while keeping checkbox semantics and the full-card
click target — see hiding the input for what that
looks like.
<zn-checkbox-group label="Choose add-ons" name="addons" contained horizontal wrap> <zn-checkbox value="support" card-title="Priority support" description="One hour response time" control-position="none"></zn-checkbox> <zn-checkbox value="backups" card-title="Daily backups" description="Retained for 30 days" control-position="none"></zn-checkbox> <zn-checkbox value="audit" card-title="Audit log" description="Exportable as CSV" control-position="none"></zn-checkbox> </zn-checkbox-group>
Card dimensions can be adjusted with --zn-selection-card-image-width,
--zn-selection-card-image-height, --zn-selection-card-min-height,
--zn-selection-card-content-min-width, and --zn-selection-card-title-font-size.
Use --zn-selection-card-padding for the inset around the card,
--zn-selection-card-gap for the space between its regions,
--zn-selection-card-control-offset for indicator placement,
--zn-selection-card-border-radius for the corner radius, and
--zn-checkbox-group-column-width on the group to control how many cards sit in a row.
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">Click Checkbox</zn-button> <zn-button id="focus-btn" color="info">Focus Checkbox</zn-button> <zn-button id="blur-btn" color="secondary">Blur Checkbox</zn-button> <zn-button id="validate-btn" 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.1.138/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.1.138/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. |
image
|
Replaces the built-in image used by contained checkboxes. |
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
|
- | |
cardTitle
card-title
|
Title rendered inside the card. The default slot takes precedence when provided. |
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
|
square
|
Squares off the corners of the container drawn by contained, which is rounded by
default.
|
|
boolean
|
false
|
src
|
URL for the image shown in a contained checkbox. |
string
|
''
|
|
imageAlt
image-alt
|
Accessible text for the built-in image. Leave empty when the image is decorative. |
string
|
''
|
|
imagePosition
image-position
|
Places the image above, beside, or below the checkbox’s text. Requires contained.
|
|
SelectionCardImagePosition
|
'left'
|
controlPosition
control-position
|
Places the checkbox indicator within a contained card. Use none to hide the indicator
so the card itself shows the selected state. Requires contained.
|
|
SelectionCardControlPosition
|
'start'
|
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.
Custom Properties
| Name | Description | Default |
|---|---|---|
--zn-selection-card-image-width |
Width of the built-in card image. | |
--zn-selection-card-image-height |
Height of the built-in card image. | |
--zn-selection-card-min-height |
Minimum height of a contained checkbox with an image. | |
--zn-selection-card-content-min-width |
Width the card text keeps before it wraps below the image. | |
--zn-selection-card-title-font-size |
Font size of a selection card title. | |
--zn-selection-card-padding |
Equal inset around the contents of a selection card. | |
--zn-selection-card-gap |
Space between the image, title, and indicator gutter. | |
--zn-selection-card-control-offset |
Distance between a positioned control and the card edge. | |
--zn-selection-card-border-radius |
Corner radius of a contained container. |
Learn more about customizing CSS custom properties.
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. |
image-container |
The wrapper around the built-in image or image slot. |
image |
The built-in image. |
card-title |
The title inside a selection card. |
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>