TriStateCheckbox

TriStateCheckbox is an extension to the Checkbox component with an additional state.

Import #


import { TriStateCheckboxModule } from 'primeng/tristatecheckbox';

Basic #

A model can be bound using the standard ngModel directive.

null


<p-triStateCheckbox class="p-tristatecheckbox-label" [(ngModel)]="value" inputId="tricheckbox"></p-triStateCheckbox>

Reactive Forms #

TriStateCheckbox can also be used with reactive forms. In this case, the formControlName property is used to bind the component to a form control.


<form [formGroup]="formGroup" class="flex flex-column align-items-center gap-3">
    <p-triStateCheckbox formControlName="checked" inputId="checked"></p-triStateCheckbox>
    <label class="p-tristatecheckbox-label" for="checked">{{ formGroup.value.checked === null ? 'null' : formGroup.value.checked }}</label>
</form>

Disabled #

When disabled is present, the element cannot be edited and focused.


<p-triStateCheckbox [(ngModel)]="value" [disabled]="true"></p-triStateCheckbox>

Style #

Following is the list of structural style classes, for theming classes visit theming page.

Name	Element
p-checkbox	Container element
p-tristatechkbox	Container element
p-checkbox-box	Container of icon.
p-checkbox-icon	Icon element.

Accessibility #

Screen Reader

TriStateCheckbox component uses an element with checkbox role. Value to describe the component can either be provided with ariaLabelledBy or ariaLabel props. Component adds an element with aria-live attribute that is only visible to screen readers to read the value displayed. Values to read are defined with the trueLabel, falseLabel and nullLabel keys of the aria property from the locale API. This is an example of a custom accessibility implementation as there is no one to one mapping between the component design and the WCAG specification.


<span id="chkbox1">Remember Me</span>
<p-triStateCheckbox ariaLabelledBy="chkbox1"></p-triStateCheckbox>

<p-triStateCheckbox ariaLabel="Remember Me"></p-triStateCheckbox>

Keyboard Support

Key	Function
tab	Moves focus to the checkbox.
space	Toggles between the values.
enter	Toggles between the values.

TriStateCheckbox API

API defines helper props, events and others for the PrimeNG TriStateCheckbox module.

TriStateCheckbox #

TriStateCheckbox is used to select either 'true', 'false' or 'null' as the value.

Properties #

Defines the input properties of the component.

name	type	default	description
disabled	boolean	false	When present, it specifies that the element should be disabled.
name	string	null	Name of the component.
ariaLabel	string	null	Defines a string that labels the input for accessibility.
ariaLabelledBy	string	null	Establishes relationships between the component and label(s) where its value should be one or more element IDs.
tabindex	number	null	Index of the element in tabbing order.
inputId	string	null	Identifier of the focus input to match a label defined for the component.
style	Object	null	Inline style of the component.
styleClass	string	null	Style class of the component.
label	string	null	Label of the checkbox.
readonly	boolean	false	When present, it specifies that the component cannot be edited.
checkboxTrueIcon	string	null	Specifies the icon for checkbox true value.
checkboxFalseIcon	string	null	Specifies the icon for checkbox false value.

Emitters #

Defines emit that determine the behavior of the component based on a given condition or report the actions that the component takes.

name	parameters	description
onChange	event : TriStateCheckboxChangeEvent	Callback to invoke on value change.

Templates #

Defines the templates used by the component.

name	parameters	description
checkicon	null	Custom check icon template.
uncheckicon	null	Custom uncheck icon template.

Events #

Defines the custom events used by the component's emitters.

TriStateCheckboxChangeEvent #

Custom change event.

name	type	description
originalEvent	Event	Browser event.
value	boolean	Value of the checkbox.