TriStateCheckbox

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


import { TriStateCheckbox } from 'primereact/tristatecheckbox';
         

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


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

Invalid state style is added using the p-invalid class to indicate a failed validation.


<TriStateCheckbox value={value} onChange={(e) => setValue(e.value)} className="p-invalid" />
         

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


<TriStateCheckbox disabled />
         

Compatibility with popular React form libraries.

Formik is a popular library for handling forms in React.

* I've read and accept the terms & conditions.
 

<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" />
 

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" />
         

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

KeyFunction
tabMoves focus to the checkbox.
spaceToggles between the values.
enterToggles between the values.