jb-switch

jb-switch is a form-associated boolean switch web component with captions, loading state, validation, and cancellable change flow.

• Submits "true" or "false" as a form value.
• Supports true and false captions.
• Supports loading animation.
• Supports disabled and required states.
• Dispatches cancellable before-change before committing a new value.
• Uses jb-validation for custom validation.

When to use

Use jb-switch for a boolean setting that can be turned on or off. See the basic switch demo for the default interaction.

Use jb-checkbox when the UI should look like a checkbox or when the boolean is part of a list of choices.

Demo

• Explore the switch examples, including loading behavior, cancellable changes, and RTL captions.

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-switch

import 'jb-switch';

<jb-switch name="enabled" true-title="Enabled" false-title="Disabled"></jb-switch>

API reference

Attributes

| name | type | default | description | | --- | --- | --- | --- | | value | boolean | false | Switch value. Only "true" means true; see the value demo. | | name | string | "" | Form field name. | | true-title | string | "" | Caption shown on the true side; see RTL captions. | | false-title | string | "" | Caption shown on the false side; see RTL captions. | | disabled | boolean | false | Disables user interaction. Empty attribute and "true" mean true. | | loading | boolean | false | Shows loading animation. Empty attribute and "true" mean true; see the loading demo. | | required | boolean | false | Requires the value to be true for validation. Empty attribute and "true" mean true; see validation. |

Properties

| name | type | readonly | description | | --- | --- | --- | --- | | value | boolean | no | Current boolean value; see initial and controlled values. | | isLoading | boolean | no | Shows or hides loading animation; see the loading action demo. | | disabled | boolean | no | Enables or disables user interaction. | | required | boolean | no | Requires the value to be true for validation; see validation. | | validation | ValidationHelper<boolean> | yes | Validation helper from jb-validation; set validation.list for custom rules. | | form | HTMLFormElement \| null | yes | Associated form from ElementInternals. | | name | string | yes | Form field name from the name attribute. | | initialValue | boolean | no | Default and reset value. It initializes value until the live value is explicitly set; see initial value. | | isDirty | boolean | yes | true when current value differs from initialValue. | | validationMessage | string | yes | Current validation message from ElementInternals. |

Methods

| name | returns | description | | --- | --- | --- | | checkValidity() | boolean | Runs validation without showing an error message; see the event/validation demo. | | reportValidity() | boolean | Runs validation and requests visible error handling; see required validation. | | focus() | void | Public focus method placeholder. Keyboard focus management is not currently implemented. | | clearValidationError() | void | Placeholder for clearing visible validation error UI. |

Events

| event | cancelable | description | | --- | --- | --- | | load | no | Dispatched from connectedCallback before initialization; see the event demo. | | init | no | Dispatched from connectedCallback after initialization; see the event demo. | | before-change | yes | Dispatched before committing a user-triggered value change. Call preventDefault() to cancel; see cancellable changes. | | change | yes | Dispatched after value changes. Call preventDefault() to revert the committed change; see cancellable changes. |

Value

Use the boolean value property for runtime updates; see the normal value demo, initial value/reset flow, and controlled value precedence.

const switchEl = document.querySelector('jb-switch');

console.log(switchEl.value);
switchEl.value = true;

<jb-switch value="true"></jb-switch>
<jb-switch value="false"></jb-switch>

Only value="true" sets the value to true. value="false", an empty value, or a missing value sets it to false.

Cancellable change

Use before-change to reject a toggle before it commits, or cancel change to revert it. The event demo covers both paths.

During before-change, event.target.value returns the intended next value.

const switchEl = document.querySelector('jb-switch');

switchEl.addEventListener('before-change', (event) => {
  if (event.target.value === true && !canEnable()) {
    event.preventDefault();
  }
});

change is also cancelable. If you call preventDefault() on change, the component reverts the value.

Loading state

Set loading in HTML or isLoading in JavaScript while an async save is running; see the loading action demo.

<jb-switch loading></jb-switch>

const switchEl = document.querySelector('jb-switch');

switchEl.isLoading = true;
switchEl.isLoading = false;

Captions and RTL

Use true-title and false-title to explain both states. The RTL demo shows captions in a right-to-left layout.

Validation

Use required when the switch must be true and validation.list for custom rules; see the validation and events demo.

<jb-switch required></jb-switch>

Use validation.list for custom validation rules. For advanced validators, see jb-validation.

const switchEl = document.querySelector('jb-switch');

switchEl.validation.list = [
  {
    validator: (value) => value === true,
    message: 'Switch must be enabled',
  },
];

CSS parts and variables

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

jb-switch {
  --jb-switch-bg-color-active: green;
  --jb-switch-ring-color-active: green;
}

Accessibility notes

• The component attaches ElementInternals and sets role to switch where supported. See the basic switch demo for the rendered control.
• Keyboard control and focus behavior are not currently implemented.
• Use clear captions or surrounding label text so users know what setting the switch controls.

Related Docs

• See jb-switch/react if you want to use this component in React.
• See jb-validation for validation rules.
• 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-switch once before using <jb-switch>.
• Use value="true" in HTML for true; value="false" is false.
• Use the value property for programmatic boolean updates.
• Use isLoading in JavaScript and loading in HTML.
• Listen to before-change to validate or confirm before committing.
• Listen to change for committed value changes.
• 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 JavaScript/TypeScript exports and exports.kind: "custom-element-definition" maps the jb-switch tag name to JBSwitchWebComponent.