TriStateCheckbox

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

Import#


import { TriStateCheckbox } from 'primereact/tristatecheckbox';

Basic#

TriStateCheckbox is used as a controlled input with checked and onChange properties.

null


<TriStateCheckbox value={value} onChange={(e) => setValue(e.value)} />

Disabled#

With disabled it specifies that the element value cannot be altered.

Disabled


<TriStateCheckbox disabled value={value} onChange={(e) => setValue(e.value)} />

Invalid#

Invalid


<TriStateCheckbox className="p-invalid" />
<label>Invalid</label>

Form#

Compatibility with popular React form libraries.

Formik#

Formik is a popular library for handling forms in React.


<Toast ref={toast} />
<TriStateCheckbox
    id="item"
    name="item"
    value={formik.values.item}
    onChange={(e) => {
        formik.setFieldValue('item', e.value);
    }}
    className={classNames({ 'p-invalid': formik.errors.item })}
/>
<div className="my-2">* I've read and accept the terms & conditions.</div>
{getFormErrorMessage('item')}
<Button type="submit" label="Submit" icon="pi pi-check" />

Hook Form#

React Hook Form is another popular React library to handle forms.


<Toast ref={toast} />
<Controller
    name="value"
    control={control}
    rules={{ required: 'Value is required.' }}
    render={({ field, fieldState }) => (
        <>
            <TriStateCheckbox id={field.name} value={field.value} ref={field.ref} onChange={field.onChange} className={classNames({ 'p-invalid': fieldState.error })} />
            <label>* I've read and accept the terms & conditions.</label>
            {getFormErrorMessage(field.name)}
        </>
    )}
/>
<Button label="Submit" type="submit" icon="pi pi-check" />

Style#

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

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

Accessibility guide documents the specification of this component based on WCAG guidelines, the implementation is in progress.

Accessibility#

Screen Reader

TriStateCheckbox component uses an element with checkbox role. Value to describe the component can either be provided with aria-labelledby or aria-label props. Component adds an element witharia-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 ariaproperty 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>
<TriStateCheckbox aria-labelledby="chkbox1" />

<TriStateCheckbox aria-label="Remember Me" />

Keyboard Support

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

API#

Visit the API documentation for detailed information about all the properties, events and methods of the component.

TriStateCheckbox