> For the complete documentation index, see [llms.txt](https://help.adalo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.adalo.com/component-basics/marketplace-components/option-selector.md).
# Option Selector
The Option Selector lets users pick from a row of styled buttons -- circles, squares, or anything in between -- and makes the selected value available via Magic Text. It supports up to 10 configurable options, an optional follow-up sub-options row that appears after a selection is made, and full style control over shape, size, color, and typography.
## Getting Started
Add the component to any screen. By default it shows five buttons labeled 1--5. Tap a button to select it -- the selection is highlighted and the value is available as **Selected Value** in Magic Text wherever you need it. To configure your own labels and values, expand each Option section in the properties panel.
## Settings
### Label Above
Optional text shown above the button row. Leave blank to hide it. Useful for a question prompt like "How would you rate your experience?"
### Label Below
Optional text shown below the button row. Leave blank to hide it.
### Default Value
The value pre-selected when the component loads (default: `1`). Must match the **Value** field of one of your options. Leave blank to start with nothing selected.
### Enable Sub-Options
Toggle this on to show a second row of buttons after the user makes a primary selection. Each option can have its own unique set of sub-options. The sub-options row replaces the primary row in place -- no layout shift. An X button appears to the right, which clears both selections and resets to the primary row.
***
## Option 1 -- 10 (Sections)
Each option is configured in its own expandable section. Options 1--5 are active by default. Options 6--10 are hidden until you add a Label.
### Label
The text shown inside the button. Can be a number, word, emoji, or any short string.
### Value
The value emitted via Magic Text when this option is selected. If left blank, the Label is used as the value. Useful when you want to display "Good" but store `3`.
### Sub-Labels
Comma-separated labels for the follow-up row shown when this option is tapped (e.g. `Morning,Afternoon,Evening`). Only used when **Enable Sub-Options** is on. Leave blank to show no sub-options for this pick.
### Sub-Values
Comma-separated values emitted via Magic Text when a sub-option is selected. Leave blank to use the Sub-Labels as values.
***
## Style (Section)
One style setting applies to all buttons uniformly.
### Button Size
Width and height of each button in pixels (default: 56). Applies to both primary and sub-option buttons.
### Roundness
Controls corner radius from 0 (square) to 50 (fully circular) (default: 28). The slider maps proportionally to the button size so the shape stays consistent if you resize buttons.
### Border Width
Thickness of the button border in pixels (default: 2). Set to 0 to remove borders entirely.
### Font Size
Size of the text inside each button (default: 18).
### Font Weight
Weight of the text: Light, Regular, Medium, Semi-Bold, or Bold (default: Semi-Bold).
### Spacing Between Buttons
Gap between each button in pixels (default: 8).
### Unselected Background
Fill color of buttons that are not selected (default: transparent).
### Unselected Border
Border color of unselected buttons (default: #000000).
### Unselected Text
Text color of unselected buttons (default: #000000).
### Selected Background
Fill color of the selected button (default: #e0e0e0).
### Selected Border
Border color of the selected button (default: #F5A623).
### Selected Text
Text color of the selected button (default: #1A2340).
### Label Text Color
Color of the Label Above and Label Below text (default: #000000).
### Label Font Size
Font size of the Label Above and Label Below text (default: 14).
### X Button Color
Color of the reset X button that appears when sub-options are shown (default: #000000).
### X Button Height Offset
Vertical position of the X button relative to the sub-options row. Negative values move it up, positive values move it down (default: 2). Adjust this to fine-tune the X button placement for your layout.
***
## Magic Text Outputs
### Selected Value
The **Value** of the currently selected primary button. Updates immediately when the user taps. Clears to empty when the X button is pressed.
### Sub-Option Value
The **Sub-Value** of the currently selected sub-option button. Updates immediately when the user taps a sub-option. Clears to empty when the X button is pressed or a new primary option is selected.
***
Resetting the Component After an Action\
The Option Selector can be reset programmatically -- returning to the primary options row with nothing selected -- by updating the value bound to **Default Value** from an action.
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
#### How it works
Whenever the **Default Value** prop changes (to any value), the component automatically resets: the sub-options panel collapses, both selections clear, and the primary options row is shown again.
#### Setup
* Add a **Date & Time** field (or any field) to your database collection -- for example, call it `last_reset`.
* Bind the **Default Value** prop on the Option Selector to that field via Magic Text.
* In your action chain (after recording the user's selections), add an **Update Record** action that sets `last_reset` to **Current Time**.
Each time the action fires and updates `last_reset`, the Option Selector detects the change and resets back to the primary options -- ready for the next selection.
#### Why Date & Time works well
A Date & Time field updated to **Current Time** is always a new, unique value on each action -- so the component reliably detects the change every time, even if the action fires multiple times in a row. A Number field incremented by 1 works equally well.
## Tips & Best Practices
* **Connect Selected Value directly to a database field** using an Update action so responses are saved as soon as the user taps.
* **Use Value to store machine-readable data** and Label for display -- for example, Label "Excellent" with Value `5` for a rating scale.
* **Leave Sub-Labels blank for options that need no follow-up** -- the sub-options row simply won't appear when those options are tapped.
* **Use the Roundness slider** to match your app's design system -- set it to 0 for a flat card-style picker or 50 for classic circular buttons.
* **Set Default Value to blank** if you want to force the user to make a conscious choice rather than accepting a pre-selected answer.
* **The X button resets everything** -- both Selected Value and Sub-Option Value are cleared. Wire a separate action to the X press if you need to react to resets.
* **Sub-option rows appear in the same position** as the primary row, so the component height stays fixed regardless of whether sub-options are visible.
***
## Example Use Cases
**Survey or feedback form** -- Set options to 1--5 or Bad/OK/Good/Great/Excellent. Connect Selected Value to a Rating field on a record. Use Sub-Options to ask a follow-up question ("What specifically was bad?").
**Appointment time slot picker** -- Label options with time ranges (Morning, Afternoon, Evening). Sub-options for each show specific slots (9am, 10am, 11am). Store both the period and the time via Magic Text.
**Product configurator** -- Use options for a top-level choice (Size, Color, Material) and sub-options to refine. Both values feed into a custom action or record update.
**Onboarding questionnaire** -- Chain multiple Option Selector components on a screen, one per question. Collect all Selected Values via Magic Text and write them to a user profile record.
**Priority selector** -- Options: Low, Medium, High, Critical. Each has a corresponding numeric value (1--4) stored via Value, while the Label stays human-readable.
---
# 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:
```
GET https://help.adalo.com/component-basics/marketplace-components/option-selector.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.