Choice Set

avonni-choice-set

A set of selectable choices rendered as radio buttons, checkboxes or buttons, for single or multiple selection.

Overview

Choice Set is a Lightning Web Component that presents a group of selectable options as radios, buttons, or toggles, supporting single or multiple selection.

Use it in your own Lightning Web Components to capture user choices in forms— preferences, categories, plans, or settings. You control the options, the selection type, orientation, multi-select behavior, validation, and label presentation—all through the component's attributes.

Use Cases

• Single-choice fields: Pick one option, like a cabin class or plan tier.
• Multi-select fields: Choose several activities, tags, or interests.
• Button groups: Render options as segmented buttons for compact forms.
• Toggle settings: Present on/off preferences as a group of toggles.
• Required form inputs: Enforce at least one selection with validation.

---

Type Guidelines

Type	Use Case
default	Radio (single) or checkbox (multi) option lists.
button	Segmented button group; pair with type-attributes.
toggle	On/off switches, often with is-multi-select.

---

Use Case Examples

Example 1: Multi-select activity picker

Scenario: Let users pick one or more trip activities, laid out in a responsive horizontal grid, with selection required.

<!-- activityPicker.html -->
<template>
    <avonni-choice-set
        label="Trip activities"
        name="activities"
        field-level-help="Pick all the activities you want included."
        options={activityOptions}
        value={activityValue}
        orientation="horizontal"
        orientation-attributes={activityOrientation}
        is-multi-select
        required
        message-when-value-missing="Select at least one activity."
        onchange={handleChange}
    ></avonni-choice-set>
</template>

// activityPicker.js
import { LightningElement } from 'lwc';

export default class ActivityPicker extends LightningElement {
    activityOptions = [
        { label: 'Hiking', value: 'hiking', iconName: 'utility:routing_offline' },
        { label: 'Diving', value: 'diving', iconName: 'utility:world' },
        { label: 'Cycling', value: 'cycling', iconName: 'utility:transport_bicycle' }
    ];
    activityOrientation = { cols: 2, smallContainerCols: 4, multipleRows: true };
    activityValue = ['hiking', 'cycling'];

    handleChange(event) {
        this.activityValue = event.detail.value; // array of selected values
    }
}

Result: A horizontal, multi-column set of selectable activity options; the field shows an error if submitted empty.

Example 2: Button-style single choice

Scenario: Present cabin classes as a stretched segmented button group with a checkmark on the selected option.

<!-- cabinSelector.html -->
<template>
    <avonni-choice-set
        label="Cabin class"
        name="cabin"
        type="button"
        type-attributes={cabinTypeAttributes}
        options={cabinOptions}
        value={cabinValue}
        orientation="horizontal"
        onchange={handleChange}
    ></avonni-choice-set>
</template>

// cabinSelector.js
import { LightningElement } from 'lwc';

export default class CabinSelector extends LightningElement {
    cabinOptions = [
        { label: 'Economy', value: 'economy' },
        { label: 'Business', value: 'business' },
        { label: 'First', value: 'first', tooltip: 'Lie-flat seats and lounge access.' }
    ];
    cabinTypeAttributes = { showCheckmark: true, stretch: true };
    cabinValue = 'business';

    handleChange(event) {
        this.cabinValue = event.detail.value; // single string value
    }
}

Result: A row of segmented buttons where one cabin class is selected and marked with a checkmark; selecting another fires change with its value.

---

Specifications

Attributes

Name	Description	Type	Default	Required
check-position	Describes the position of the toggle, radio or checkbox. Options include left and right and is not available for type button.	String	"left"
disabled	If present, the input field is disabled and users cannot interact with it.	Boolean	false
field-level-help	Help text detailing the purpose and function of the input.	String	—
is-loading	If present, the input is loading and a spinner is visible where the options should be.	Boolean	false
is-multi-select	If present, multiple choices can be selected.	Boolean	false
label	Text label for the input.	String	—	Yes
loading-state-alternative-text	Message displayed while the button is in the loading state.	String	"Loading..."
message-when-value-missing	Optional message to be displayed when no option is selected and the required attribute is set.	String	—
name	Specifies the name of an input element.	String	—	Yes
options	Array of option objects.	AvonniInputChoiceSetOption[]	—	Yes
orientation	Orientation of the input options. Valid values include vertical and horizontal.	String	"vertical"
orientation-attributes	Field attributes: cols, smallContainerCols, mediumContainerCols, largeContainerCols and multipleRows.	AvonniInputChoiceSetOrientationAttributes	—
read-only	If present, the input field is read-only and cannot be edited by users.	Boolean	false
required	If present, at least one option must be selected.	Boolean	false
required-alternative-text	The assistive text when the required attribute is set to true.	String	"Required"
type	Type of the input. Valid values include default, button and toggle.	String	"default"
type-attributes	Attributes specific to the type (see Types and Type Attributes).	AvonniInputChoiceSetTypeAttributes	—
validity	Represents the validity states that an element can be in, with respect to constraint validation.	String	—
value	The list of selected options. Each array entry contains the value of a selected option. The value of each option is set in the options attribute.	(string	string[])	—
variant	The variant changes the appearance of the input label. Accepted variants include standard, label-hidden, label-inline, and label-stacked. Use label-hidden to hide the label but make it available to assistive technology. Use label-inline to horizontally align the label and checkbox group. Use label-stacked to place the label above the checkbox group.	String	"standard"

Methods

Name	Description	Argument Name	Argument Type	Argument Description
checkValidity	Checks if the input is valid.
focus	Sets the focus on the first input option.
reportValidity	Displays the error messages. If the input is valid, reportValidity() clears displayed error messages.
setCustomValidity	Sets a custom error message to be displayed when a form is submitted.	message	String	The string that describes the error. If message is an empty string, the error message is reset.
showHelpMessageIfInvalid	Displays error messages on invalid fields. An invalid field fails at least one constraint validation and returns false when checkValidity() is called.

Custom Events

blur

The event fired when the focus is removed from the input.

The blur event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

change

The event fired when the value changed.

The change event returns the following parameters.

Parameter	Type	Description
value	string	string[]

The event properties are as follows.

Property	Value	Description
bubbles	true	This event bubbles up through the DOM.
cancelable	true	This event can be canceled. You can call preventDefault() on this event.
composed	true	This event propagates outside of the component in which it was dispatched.

focus

The event fired when you focus the input.

The focus event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

blur

The event fired when the focus is removed from the input.

The blur event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

change

The event fired when the value changed.

The change event returns the following parameters.

Parameter	Type	Description
value	string	string[]

The event properties are as follows.

Property	Value	Description
bubbles	true	This event bubbles up through the DOM.
cancelable	true	This event can be canceled. You can call preventDefault() on this event.
composed	true	This event propagates outside of the component in which it was dispatched.

focus

The event fired when you focus the input.

The focus event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

Styling Hooks

CSS Variable	Type	Default
--avonni-input-choice-set-header-text-color	color	#3e3e3c
--avonni-input-choice-set-header-font-size	font	0.75rem
--avonni-input-choice-set-header-font-style	font	normal
--avonni-input-choice-set-header-font-weight	font	400
--avonni-input-choice-set-option-button-color-background	color	#ffffff
--avonni-input-choice-set-option-button-color-background-checked	color	#0176d3
--avonni-input-choice-set-option-button-color-background-checked-hover	color	#014486
--avonni-input-choice-set-option-button-color-background-hover	color	#f3f3f3
--avonni-input-choice-set-option-button-color-background-disabled	color	#ffffff
--avonni-input-choice-set-option-button-color-border	color	#747474
--avonni-input-choice-set-option-button-color-border-checked	color	#5c5c5c
--avonni-input-choice-set-option-button-color-border-checked-hover	color	#5c5c5c
--avonni-input-choice-set-option-button-color-border-hover	color	—
--avonni-input-choice-set-option-button-color-border-disabled	color	#747474
--avonni-input-choice-set-option-button-sizing-border	dimension	1px
--avonni-input-choice-set-option-button-styling-border	string	solid
--avonni-input-choice-set-option-button-radius-border	radius	0.25rem
--avonni-input-choice-set-option-button-label-text-color	color	#0176d3
--avonni-input-choice-set-option-button-label-text-color-checked	color	#ffffff
--avonni-input-choice-set-option-button-label-text-color-checked-hover	color	—
--avonni-input-choice-set-option-button-label-text-color-hover	color	#014486
--avonni-input-choice-set-option-button-label-text-color-disabled	color	#c9c9c9
--avonni-input-choice-set-option-button-label-font-size	font	0.8125rem
--avonni-input-choice-set-option-button-label-font-style	font	normal
--avonni-input-choice-set-option-button-label-font-weight	font	400
--avonni-input-choice-set-option-checkbox-color-background	color	—
--avonni-input-choice-set-option-checkbox-color-background-checked	color	—
--avonni-input-choice-set-option-checkbox-color-foreground	color	—
--avonni-input-choice-set-option-checkbox-color-border	color	—
--avonni-input-choice-set-option-checkbox-color-border-checked	color	—
--avonni-input-choice-set-option-checkbox-radius-border	radius	—
--avonni-input-choice-set-option-label-text-color	color	#444
--avonni-input-choice-set-option-label-font-size	font	0.8125rem
--avonni-input-choice-set-option-label-font-style	font	normal
--avonni-input-choice-set-option-label-font-weight	font	400
--avonni-input-choice-set-option-label-line-clamp	number	1
--avonni-input-choice-set-option-toggle-color-background	color	#aeaeae
--avonni-input-choice-set-option-toggle-color-background-checked	color	#0176d3
--avonni-input-choice-set-option-toggle-color-background-checked-focus	color	#014486
--avonni-input-choice-set-option-toggle-color-background-checked-hover	color	#014486
--avonni-input-choice-set-option-toggle-color-background-hover	color	#939393
--avonni-input-choice-set-option-toggle-color-border	color	#aeaeae
--avonni-input-choice-set-option-toggle-color-border-checked	color	#0176d3
--avonni-input-choice-set-option-toggle-color-border-hover	color	—
--avonni-input-choice-set-option-toggle-color-foreground	color	#ffffff
--avonni-input-choice-set-option-toggle-switch-color-background	color	#ffffff
--avonni-input-choice-set-option-toggle-switch-color-background-checked	color	#ffffff
--avonni-input-choice-set-option-toggle-radius-border	radius	15rem
--avonni-input-choice-set-option-button-sizing-border-disabled	sizing	1px
--avonni-input-choice-set-option-button-styling-border-disabled	string	solid
--avonni-input-choice-set-overflow-button-color-background	color	—
--avonni-input-choice-set-overflow-button-color-background-active	color	—
--avonni-input-choice-set-overflow-button-color-background-hover	color	—
--avonni-input-choice-set-overflow-button-color-border	color	—
--avonni-input-choice-set-overflow-button-color-border-active	color	—
--avonni-input-choice-set-overflow-button-color-border-hover	color	—
--avonni-input-choice-set-overflow-button-spacing-block-end	dimension	—
--avonni-input-choice-set-overflow-button-spacing-block-start	dimension	—
--avonni-input-choice-set-overflow-button-spacing-inline-end	dimension	—
--avonni-input-choice-set-overflow-button-spacing-inline-start	dimension	—
--avonni-input-choice-set-overflow-button-text-color	color	—
--avonni-input-choice-set-overflow-button-text-color-active	color	—
--avonni-input-choice-set-overflow-button-text-color-hover	color	—

Key Considerations

• Value shape: change returns a string for single select and an array when is-multi-select is set—handle both shapes in your handler.
• Validation: Use required with message-when-value-missing, and call reportValidity() to surface errors on submit.
• Type attributes: Toggle and button types accept extra options through type-attributes (e.g. showCheckmark, stretch, messageToggleActive).
• Responsive layout: Use orientation-attributes to set column counts per container size.
• Accessibility: Always provide label; use variant="label-hidden" only when the label is conveyed visually elsewhere.
• Best Practice: Set is-multi-select to match the data shape of value—use a string for single selection and an array when multiple choices are allowed.

---

Troubleshooting Common Issues

• Selection not updating: Ensure your change handler writes event.detail.value back to the bound value property.
• Multi-select returns a string: Confirm is-multi-select is set so the value is treated as an array.
• Validation message not showing: Set required and message-when-value-missing, then call reportValidity().
• If issues persist: Contact our support team at [email protected] for assistance.