SelectButton

SelectButton is used to choose single or multiple items from a list using buttons.


import { SelectButton } from 'primereact/selectbutton';
         

SelectButton is used as a controlled component with value and onChange properties along with the options collection. Label and value of an option are defined with the optionLabel and optionValue properties respectively. Default property name for the optionLabel is label and value for the optionValue. If optionValue is omitted and the object has no value property, the object itself becomes the value of an option. Note that, when options are simple primitive values such as a string array, no optionLabel and optionValue would be necessary.

Off
On

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

SelectButton allows selecting only one item by default and enabling multiple allows choosing more. In multiple case, model property should be an array instead of a single value.

Option 1
Option 2
Option 3

<SelectButton value={value} onChange={(e) => setValue(e.value)} optionLabel="name" options={items} multiple />
         

Options support templating using the itemTemplate property that references a function to render the content. Notice the usage of optionLabel, although not rendered visually, it is still required to be used as the list key.


<SelectButton value={value} onChange={(e) => setValue(e.value)} itemTemplate={justifyTemplate} optionLabel="value" options={justifyOptions} />
         

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

Off
On

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

When disabled is present, the element cannot be edited and focused entirely. Certain options can also be disabled using the optionDisabled property.

Off
On
Option 1
Option 2

<SelectButton disabled options={options1} />
<SelectButton value={value} onChange={(e) => setValue(e.value)} options={options2} optionLabel="name" optionDisabled="constant" />
         
Compatibility with popular React form libraries.

Formik is a popular library for handling forms in React.

Off
On
 

<label htmlFor="item" className={classNames('flex justify-content-center', { 'p-error': formik.errors.item })}>
    Engine State
</label>
<SelectButton
    id="item"
    name="item"
    value={formik.values.item}
    options={options}
    onChange={(e) => {
        formik.setFieldValue('item', e.value);
    }}
    className={classNames('flex justify-content-center', { 'p-invalid': formik.errors.item })}
/>
<Button label="Submit" type="submit" icon="pi pi-check" />
         

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

Off
On
 

<Controller
    name="value"
    control={form.control}
    rules={{ required: 'Engine State is required.' }}
    render={({ field, fieldState }) => (
        <>
            <label htmlFor={field.name} className={classNames('flex justify-content-center', { 'p-error': errors.value })}>
                Engine State
            </label>
            <SelectButton id={field.name} options={options} {...field} className={classNames('flex justify-content-center', { 'p-invalid': fieldState.error })} />
            {getFormErrorMessage(field.name)}
        </>
    )}
/>
<Button label="Submit" type="submit" icon="pi pi-check" />
         
Accessibility guide documents the specification of this component based on WCAG guidelines, the implementation is in progress.

Screen Reader

The container element that wraps the buttons has a group role whereas each button element uses button role and aria-pressed is updated depending on selection state. Value to describe an option is automatically set using the aria-label property that refers to the label of an option so it is still suggested to define a label even the option display consists of presentational content like icons only.

Keyboard Support

KeyFunction
tabMoves focus to the buttons.
spaceToggles the checked state of a button.
Visit the API documentation for detailed information about all the properties, events and methods of the component.