State toggle button: on or off. For example, Wi-Fi is turned on or off on a phone.

Properties

Disabled state

Error

Validation

To show a validation error, bind the toggle to a form control, apply Validators.requiredTrue, and put the error text in a kbq-error inside the toggle.

To show the error at another moment, pass a matcher to the errorStateMatcher input. The matchers are described in the Validation guide.

Indeterminate state

This state is used to reflect partial selection or uncertainty.

Loading

While loading, the toggle looks inactive, ignores clicks, but stays focusable.

Big

Use the big input to render the toggle with the enlarged typography of the label and the hint. The switch itself keeps its size.

Content

Hint

Label on the left

The toggle is placed to the right of the field name and hint block. Use labelPosition="left" for this layout, the default value is right.

The toggle can be placed to the right and on the same line after the label.

Accessibility

Without a visible label, describe the toggle with aria-label or point aria-labelledby at an existing caption. A projected kbq-hint is exposed as the description of the control and is not part of its name.

The name and value inputs are forwarded to the underlying <input type="checkbox">, so the toggle is serialized by native form submission.

Recommendations

• Use a toggle for instant switching of settings that do not require confirmation. For example, changes are applied immediately without a “Save” button. If saving requires submitting a form, use a checkbox.
• Do not use a toggle if the choice options do not fit binary logic: on or off, yes or no.
• Use clickAction (or the KBQ_CHECKABLE_CLICK_ACTION token for the whole application) to change what a click does: check-indeterminate is the default, check keeps the mixed state, and noop leaves the state to the application.