Checkbox
import {CheckboxModule} from "@qualcomm-ui/angular/checkbox"Examples
Simple
The simple API bundles the subcomponents together into a single directive.
Qualcomm
<label label="Label" q-checkbox></label>Child Directives
Provide child directives to customize specific elements while keeping the simple API's default structure.
Qualcomm
<label q-checkbox>
<div q-checkbox-label>Label</div>
</label>Composite
Build with the composite API for granular control. This API requires you to provide each subcomponent, but gives you full control over the structure and layout.
Qualcomm
<label q-checkbox-root>
<input q-checkbox-hidden-input />
<div q-checkbox-control></div>
<span q-checkbox-label>Label</span>
</label>States
Based on the inputs, the checkbox will render as checked, indeterminate, or unchecked (default). The controlled value, if supplied as true, takes precedence over the indeterminate input.
Qualcomm
Checked
Unchecked
Indeterminate
<label defaultChecked label="Label" q-checkbox></label>
<label label="Label" q-checkbox></label>
<label indeterminate label="Label" q-checkbox></label>Disabled State
When disabled is true, the checkbox becomes non-interactive and is typically rendered with reduced opacity to indicate its unavailable state.
Qualcomm
<label defaultChecked disabled label="Label" q-checkbox></label>
<label disabled label="Label" q-checkbox></label>
<label disabled indeterminate label="Label" q-checkbox></label>Sizes
The checkbox supports three sizes: sm, md (default), and lg.
Qualcomm
import {Component} from "@angular/core"
import {CheckboxModule} from "@qualcomm-ui/angular/checkbox"
@Component({
imports: [CheckboxModule],
selector: "checkbox-sizes-demo",
template: `
<div class="flex flex-col items-start gap-4">
<label label="Small (sm)" q-checkbox size="sm"></label>
<label label="Medium (md)" q-checkbox size="md"></label>
<label label="Large (lg)" q-checkbox size="lg"></label>
</div>
`,
})
export class CheckboxSizesDemo {}
Forms
Template Forms
- When using template forms, add the required attribute to enable validation
- The errorText input (or
q-checkbox-error-textdirective) displays automatically when the field is invalid and the user has interacted with it
Qualcomm
<label
errorText="Please accept the Terms of Service to continue"
label="Accept Terms of Service"
name="acceptTerms"
q-checkbox
required
[(ngModel)]="acceptTerms"
></label>Reactive Forms
Use Reactive Forms instead of Template-driven Forms for better control over form state and validation.
Qualcomm
Multi-Field Validation
Reactive forms let you validate across multiple fields simultaneously, perfect for complex business rules like date ranges or dependent field relationships.
Qualcomm
Composition
The composite elements are only intended to be used as direct descendants of the q-checkbox directive.
<!-- Won't work alone ❌ -->
<input q-checkbox-hidden-input />
<div q-checkbox-control></div>
<!-- Works as expected ✅ -->
<div q-checkbox-root>
<input q-checkbox-hidden-input />
<div q-checkbox-control></div>
</div>Accessibility
- The root directive should always be attached to a
<label>element for accessibility:- it makes the entire component clickable, not just the input/control.
- it provides implicit association between the text and input element, which is ideal for screen readers.
- Always use the associated label or q-checkbox-label directive when authoring the text label. This is automatically associated with the input element.
- If you omit the label, you must provide an aria-label or aria-labelledby attribute on the
q-checkbox-hidden-inputelement.
API
q-checkbox
The q-checkbox directive extends the q-checkbox-root directive with the following properties:
Groups all parts of the checkbox.
| Prop | Type | Default |
|---|---|---|
The initial checked state of the checkbox when rendered. Use when you don't
need to control the checked state of the checkbox. This property will be
ignored if you opt into controlled state via form control bindings. | boolean | |
The document's text/writing direction. | 'ltr' | 'rtl' | "ltr" |
Controls whether the input is disabled in template-driven forms. When true,
prevents user interaction and applies visual styling to indicate the disabled
state. | boolean | |
Optional error that describes the checkbox when the field is invalid. This
element is automatically associated with the checkbox for accessibility. | string | |
To customize the element, provide it using the directive instead: <label q-checkbox> | ||
A root node to correctly resolve the Document in custom environments. i.e.,
Iframes, Electron. | () => | |
id attribute. If
omitted, a unique identifier will be generated for accessibility.) | string | |
If true and the checkbox is not checked, the checkbox will be in the
indeterminate state. | boolean | |
Optional label describing the checkbox. This element is automatically
associated with the checkbox for accessibility. If omitted, you should provide
an aria-label or aria-labelledby attribute on the q-checkbox-hidden-input
element. | string | |
To customize the element, provide it using the directive instead: <label q-checkbox> | ||
The name of the input field in a checkbox. Useful for form submission. | string | |
Whether the input is read-only. When true, prevents user interaction while
keeping the input focusable and visible. | boolean | |
Controls whether the input is required in template-driven forms. When
true, the input must have a value for form validation to pass. | boolean | |
The size of the checkbox and its elements. Governs properties like label font
size, control size, and indicator size. | | 'sm' | 'md' |
The value of checkbox input. Useful for form submission. | string | "on" |
Event emitted when the checkbox is checked or unchecked. This is only emitted
on interaction. It doesn't emit in response to programmatic form control
changes. | boolean | |
Type
booleanDescription
The initial checked state of the checkbox when rendered. Use when you don't
need to control the checked state of the checkbox. This property will be
ignored if you opt into controlled state via form control bindings.
Type
'ltr' | 'rtl'
Description
The document's text/writing direction.
Type
booleanDescription
Controls whether the input is disabled in template-driven forms. When true,
prevents user interaction and applies visual styling to indicate the disabled
state.
Type
stringDescription
Optional error that describes the checkbox when the field is invalid. This
element is automatically associated with the checkbox for accessibility.
To customize the element, provide it using the directive instead:
<label q-checkbox>
<div q-checkbox-error-text>...</div>
</label>
Type
() =>
| Node
| ShadowRoot
| Document
Description
A root node to correctly resolve the Document in custom environments. i.e.,
Iframes, Electron.
Type
stringDescription
id attribute. If
omitted, a unique identifier will be generated for accessibility.)
Type
booleanDescription
If true and the checkbox is not checked, the checkbox will be in the
indeterminate state.Type
stringDescription
Optional label describing the checkbox. This element is automatically
associated with the checkbox for accessibility. If omitted, you should provide
an
aria-label or aria-labelledby attribute on the q-checkbox-hidden-input
element.To customize the element, provide it using the directive instead:
<label q-checkbox>
<div q-checkbox-label>...</div>
</label>
Type
stringDescription
The name of the input field in a checkbox. Useful for form submission.
Type
booleanDescription
Whether the input is read-only. When true, prevents user interaction while
keeping the input focusable and visible.
Type
booleanDescription
Controls whether the input is required in template-driven forms. When
true, the input must have a value for form validation to pass.
Type
| 'sm'
| 'md'
| 'lg'
Description
The size of the checkbox and its elements. Governs properties like label font
size, control size, and indicator size.
Type
stringDescription
The value of checkbox input. Useful for form submission.
Type
booleanDescription
Event emitted when the checkbox is checked or unchecked. This is only emitted
on interaction. It doesn't emit in response to programmatic form control
changes.
Composite API
q-checkbox-root
Groups all parts of the checkbox.
| Prop | Type | Default |
|---|---|---|
The initial checked state of the checkbox when rendered. Use when you don't
need to control the checked state of the checkbox. This property will be
ignored if you opt into controlled state via form control bindings. | boolean | |
The document's text/writing direction. | 'ltr' | 'rtl' | "ltr" |
Controls whether the input is disabled in template-driven forms. When true,
prevents user interaction and applies visual styling to indicate the disabled
state. | boolean | |
A root node to correctly resolve the Document in custom environments. i.e.,
Iframes, Electron. | () => | |
id attribute. If
omitted, a unique identifier will be generated for accessibility.) | string | |
If true and the checkbox is not checked, the checkbox will be in the
indeterminate state. | boolean | |
The name of the input field in a checkbox. Useful for form submission. | string | |
Whether the input is read-only. When true, prevents user interaction while
keeping the input focusable and visible. | boolean | |
Controls whether the input is required in template-driven forms. When
true, the input must have a value for form validation to pass. | boolean | |
The size of the checkbox and its elements. Governs properties like label font
size, control size, and indicator size. | | 'sm' | 'md' |
The value of checkbox input. Useful for form submission. | string | "on" |
Event emitted when the checkbox is checked or unchecked. This is only emitted
on interaction. It doesn't emit in response to programmatic form control
changes. | boolean |
Type
booleanDescription
The initial checked state of the checkbox when rendered. Use when you don't
need to control the checked state of the checkbox. This property will be
ignored if you opt into controlled state via form control bindings.
Type
'ltr' | 'rtl'
Description
The document's text/writing direction.
Type
booleanDescription
Controls whether the input is disabled in template-driven forms. When true,
prevents user interaction and applies visual styling to indicate the disabled
state.
Type
() =>
| Node
| ShadowRoot
| Document
Description
A root node to correctly resolve the Document in custom environments. i.e.,
Iframes, Electron.
Type
stringDescription
id attribute. If
omitted, a unique identifier will be generated for accessibility.)
Type
booleanDescription
If true and the checkbox is not checked, the checkbox will be in the
indeterminate state.Type
stringDescription
The name of the input field in a checkbox. Useful for form submission.
Type
booleanDescription
Whether the input is read-only. When true, prevents user interaction while
keeping the input focusable and visible.
Type
booleanDescription
Controls whether the input is required in template-driven forms. When
true, the input must have a value for form validation to pass.
Type
| 'sm'
| 'md'
| 'lg'
Description
The size of the checkbox and its elements. Governs properties like label font
size, control size, and indicator size.
Type
stringDescription
The value of checkbox input. Useful for form submission.
Type
booleanDescription
Event emitted when the checkbox is checked or unchecked. This is only emitted
on interaction. It doesn't emit in response to programmatic form control
changes.
| Attribute / Property | Value |
|---|---|
class | 'qui-checkbox__root' |
data-active | |
data-disabled | |
data-focus | |
data-focus-visible | |
data-hover | |
data-invalid | |
data-part | 'root' |
data-readonly | |
data-scope | 'checkbox' |
data-state | | 'checked' |
classValue
'qui-checkbox__root'data-activeValue
data-disabledValue
data-focusValue
data-focus-visibleValue
data-hoverValue
data-invalidValue
data-partValue
'root'data-readonlyValue
data-scopeValue
'checkbox'data-stateValue
| 'checked'
| 'indeterminate'
| 'unchecked'
q-checkbox-label
An accessible label that is automatically associated with the checkbox.
| Prop | Type |
|---|---|
id attribute. If
omitted, a unique identifier will be generated for accessibility. | string |
Type
stringDescription
id attribute. If
omitted, a unique identifier will be generated for accessibility.
| Attribute / Property | Value |
|---|---|
class | 'qui-checkbox__label' |
data-active | |
data-disabled | |
data-focus | |
data-focus-visible | |
data-hover | |
data-invalid | |
data-part | 'label' |
data-readonly | |
data-scope | 'checkbox' |
data-size | | 'sm' |
data-state | | 'checked' |
classValue
'qui-checkbox__label'data-activeValue
data-disabledValue
data-focusValue
data-focus-visibleValue
data-hoverValue
data-invalidValue
data-partValue
'label'data-readonlyValue
data-scopeValue
'checkbox'data-sizeValue
| 'sm'
| 'md'
| 'lg'
data-stateValue
| 'checked'
| 'indeterminate'
| 'unchecked'
q-checkbox-control
Visual control that wraps the checkbox indicator.
| Prop | Type |
|---|---|
id attribute. If
omitted, a unique identifier will be generated for accessibility. | string |
Type
stringDescription
id attribute. If
omitted, a unique identifier will be generated for accessibility.
| Attribute / Property | Value |
|---|---|
class | 'qui-checkbox__control' |
data-active | |
data-disabled | |
data-focus | |
data-focus-visible | |
data-hover | |
data-invalid | |
data-part | 'control' |
data-readonly | |
data-scope | 'checkbox' |
data-size | | 'sm' |
data-state | | 'checked' |
classValue
'qui-checkbox__control'data-activeValue
data-disabledValue
data-focusValue
data-focus-visibleValue
data-hoverValue
data-invalidValue
data-partValue
'control'data-readonlyValue
data-scopeValue
'checkbox'data-sizeValue
| 'sm'
| 'md'
| 'lg'
data-stateValue
| 'checked'
| 'indeterminate'
| 'unchecked'
q-checkbox-hidden-input
Hidden input element used for accessibility and form submissions. Note: do not
apply form control bindings like
ngModel or formControl to this element.
Apply them to the root element instead.| Prop | Type |
|---|---|
id attribute. If
omitted, a unique identifier will be generated for accessibility. | string |
Type
stringDescription
id attribute. If
omitted, a unique identifier will be generated for accessibility.
| Attribute / Property | Value |
|---|---|
class | 'qui-checkbox__hidden-input' |
data-active | |
data-disabled | |
data-focus | |
data-focus-visible | |
data-hover | |
data-invalid | |
data-part | 'hidden-input' |
data-readonly | |
data-scope | 'checkbox' |
data-state | | 'checked' |
style |
classValue
'qui-checkbox__hidden-input'data-activeValue
data-disabledValue
data-focusValue
data-focus-visibleValue
data-hoverValue
data-invalidValue
data-partValue
'hidden-input'data-readonlyValue
data-scopeValue
'checkbox'data-stateValue
| 'checked'
| 'indeterminate'
| 'unchecked'
styleValue
q-checkbox-indicator
Visual indicator rendered within the control that displays the checkbox state
(checked, indeterminate, or unchecked).
| Attribute / Property | Value |
|---|---|
class | 'qui-checkbox__indicator' |
data-active | |
data-disabled | |
data-focus | |
data-focus-visible | |
data-hover | |
data-invalid | |
data-part | 'indicator' |
data-readonly | |
data-scope | 'checkbox' |
data-size | | 'sm' |
data-state | | 'checked' |
hidden | boolean |
classValue
'qui-checkbox__indicator'data-activeValue
data-disabledValue
data-focusValue
data-focus-visibleValue
data-hoverValue
data-invalidValue
data-partValue
'indicator'data-readonlyValue
data-scopeValue
'checkbox'data-sizeValue
| 'sm'
| 'md'
| 'lg'
data-stateValue
| 'checked'
| 'indeterminate'
| 'unchecked'
hiddenValue
boolean