SelectButton

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

Import#


import { SelectButton } from 'primereact/selectbutton';

Basic#

SelectButton is used as a controlled component with value and onChange properties along with an 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


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

Multiple#

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

Template#

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#

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

Off


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

Disabled#

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

Off

Option 1

Option 2


<SelectButton disabled options={options1} />
<SelectButton value={value} onChange={(e) => setValue(e.value)} options={options2} optionLabel="name" optionDisabled="constant" />

Form#

Compatibility with popular React form libraries.

Formik#

Formik is a popular library for handling forms in React.


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

Hook Form#

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


<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.

Accessibility#

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

Key	Function
tab	Moves focus to the buttons.
space	Toggles the checked state of a button.