jb-checkbox

Checkbox web component with smooth check animation.

• Customizable UI with CSS variables and CSS parts.
• Form-associated checkbox value.
• Built-in required and external error validation.
• Custom validation through jb-validation.

When to use

Use jb-checkbox for a single boolean option that needs JB Design System styling, validation, form association, disabled state, or custom label markup.

For multiple related choices, render a list of jb-checkbox elements with different name or value handling based on your form model.

Demo

• Demo

Using With JS Frameworks

Other integrations: Angular · Vue · Nuxt · Svelte · SvelteKit · SolidJS · Lit · Next.js · Astro · Blazor · Server-rendered templates · WordPress · Alpine.js and HTMX

Installation

npm i jb-checkbox

import 'jb-checkbox';

<jb-checkbox label="Accept terms"></jb-checkbox>

Use the label slot when the label needs custom markup:

<jb-checkbox>
  <span slot="label">Accept <a href="/terms">terms</a></span>
</jb-checkbox>

API reference

Attributes

| name | type | default | description | | --- | --- | --- | --- | | value | boolean | false | Initial checked value attribute. Use value="true" for checked markup; omit the attribute or use the boolean value property for false/programmatic updates. Demo | | label | string | "" | Text label. Use slot="label" for custom markup. Demo | | message | string | "" | Helper text shown below the label when no validation error is visible. Demo | | name | string | "" | Form field name. | | disabled | boolean | false | Disables user toggling and sets the disabled custom state. Demo | | required | boolean \| string | false | Enables required validation. A string value is used as the required error message. Demo | | error | string | "" | External validation error message used as a custom error. Demo | | size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' | md style defaults | Visual size variant. Demo | | variant | 'solid' \| 'outline' \| 'filled-outline' | solid | Visual style variant. Demo | | color | 'primary' \| 'secondary' \| 'positive' \| 'danger' \| 'warning' \| 'light' \| 'dark' | primary | Semantic color variant. Demo |

Properties

| name | type | readonly | description | | --- | --- | --- | --- | | value | boolean | no | Boolean checked value. The native form value is set to "true" or "false". Demo | | checked | boolean | no | Native-style checked state synchronized with canonical boolean value. Demo | | disabled | boolean | no | Disables user toggling and updates accessibility/custom state. Demo | | required | boolean | no | Enables required validation. Demo | | validation | ValidationHelper<boolean> | yes | Validation helper from jb-validation; set validation.list for custom rules. Demo | | name | string | yes | Current name attribute value. | | initialValue | boolean | no | Default and reset value. It initializes value until the live value is explicitly set. Demo | | isDirty | boolean | yes | true when current value differs from initialValue. Demo | | isAutoValidationDisabled | boolean | no | Compatibility flag for form input standards. | | validationMessage | string | yes | Current native validation message from ElementInternals. Demo |

Methods

| name | returns | description | | --- | --- | --- | | checkValidity() | boolean | Runs validation without showing the error message. Demo | | reportValidity() | boolean | Runs validation and shows the first error message. Demo | | reset() | void | Restores initialValue and clears displayed validation. | | focus(options?) | void | Focuses the checkbox control when it is not disabled. Demo |

Events

| event | detail | description | | --- | --- | --- | | before-change | none | Cancelable event dispatched before toggling. During this event, event.target.value exposes the next value. Demo | | change | none | Cancelable event dispatched after value changes. Prevent default to revert the toggle. Demo | | load | none | Dispatched from connectedCallback before initProp. Demo | | init | none | Dispatched from connectedCallback after initProp. Demo |

Get and set value

Use the value property for controlled updates; see the controlled-value Demo.

const checkbox = document.querySelector('jb-checkbox');

checkbox.value = true;
console.log(checkbox.checked); // true

checkbox.addEventListener('change', (event) => {
  console.log(event.target.value);
});

Disable checkbox

Set the disabled property to prevent toggling and remove the checkbox from the internal tab order; see the Demo.

document.querySelector('jb-checkbox').disabled = true;

<jb-checkbox disabled></jb-checkbox>

Validation

jb-checkbox uses jb-validation. Built-in validation covers required and error; custom validations can be added with validation.list. See the imperative validation Demo.

const checkbox = document.querySelector('jb-checkbox');

checkbox.validation.list = [
  {
    validator: (value) => value === true,
    message: 'You must check this before continuing',
  },
];

const isValid = checkbox.reportValidity();

Required Validation

Use the required attribute to enable built-in validation; see the Demo.

<jb-checkbox required label="Accept terms"></jb-checkbox>
<jb-checkbox required="Please accept terms" label="Accept terms"></jb-checkbox>

External error

Set the error attribute when an external validation system owns the error state; see the external-error Demo.

<jb-checkbox error="Please accept terms" label="Accept terms"></jb-checkbox>

Sizes

Supported size values are xs, sm, md, lg, and xl; see the Demo.

<jb-checkbox size="sm" label="Small checkbox"></jb-checkbox>

Variants

Use variant to select solid, outline, or filled-outline, and use color to select a semantic color. See every style, color, checked, and disabled combination in the Variants Demo.

<jb-checkbox variant="solid" color="positive" label="Approved"></jb-checkbox>
<jb-checkbox variant="outline" color="danger" label="Remove item"></jb-checkbox>
<jb-checkbox variant="filled-outline" color="secondary" label="Optional"></jb-checkbox>

The selected color defines the component's base color. Checked and disabled states derive their background, border, and check-mark colors from that base while retaining the public CSS-variable overrides.

Slots

| slot | description | | --- | --- | | label | Custom label content rendered next to the checkbox. Demo |

CSS parts and states

| part | description | | --- | --- | | checkbox | The checkbox SVG element. | | check-bg | The checkbox background rectangle. | | check-mark | The animated check mark path. | | label | The label slot. | | message | The helper or validation message. |

| custom state | description | | --- | --- | | checked | Applied when value is true. | | disabled | Applied when disabled is true. | | invalid | Applied while a validation error is visible. |

jb-checkbox::part(label) {
  font-weight: 600;
}

jb-checkbox:state(checked)::part(label) {
  color: var(--jb-text-primary);
}

jb-checkbox:state(invalid)::part(message) {
  font-weight: 600;
}

Custom style

For complete styling guidance, live examples, CSS parts, custom states, variables, and copyable style recipes, see Styling and the style gallery Demo.

Accessibility notes

• The component uses ElementInternals.role = "checkbox" where supported; inspect the interactive Demo.
• The label attribute is exposed as ariaLabel.
• ariaChecked is synchronized with the current checked value.
• disabled, checked, and invalid states are synchronized with ElementInternals custom states where supported.
• The form property returns the associated form from ElementInternals.
• The shadow root uses delegatesFocus; calling focus() focuses the internal checkbox wrapper when the component is not disabled.
• Pressing Space toggles the checkbox when it is focused and not disabled.
• Disabled checkboxes are removed from the internal tab order.
• The component is form-associated and sets its form value to the string "true" or "false".

Related Docs

• See jb-checkbox/react if you want to use this component in React.
• See All JB Design System Component List for more components.
• Use Contribution Guide if you want to contribute to this component.

AI agent notes

• Import jb-checkbox once before using <jb-checkbox>.
• Use the boolean value property for controlled state. Avoid relying on value="false" as an HTML attribute.
• Read event.target.value in before-change for the next value and in change for the committed value.
• Use required, error, and validation.list for validation.
• Use slot="label" for custom label markup.
• Style with CSS variables, ::part(...), and :state(checked|disabled|invalid).
• This package includes custom-elements.json and points to it with the package.json customElements field. The field is documented by the Custom Elements Manifest project in Referencing manifests from npm packages.
• In custom-elements.json, exports.kind: "js" describes the JavaScript/TypeScript class export and exports.kind: "custom-element-definition" maps the jb-checkbox tag name to that class.