> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/core-components/choice-set.md).
# 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.
```html
```
```js
// 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.
```html
```
```js
// 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. |
### 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 for assistance.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.avonnicomponents.com/lwc-components/core-components/choice-set.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.