Selection item settings
A selection item is one option within a choice component: a radio button, checkbox or select-list option. These settings control what the person sees and, just as importantly, the stable value that the service stores when they select it.
Set up the selection items after you have written the main question and decided what each possible answer means to the service. A clear option is easy to choose; a stable option ID makes conditions, templates and actions dependable over time.
Open a selection item
- Open the page in the Builder and select the choice component.
- In the component settings, add an item or open an existing one.
- Set the item ID and visible text first.
- Add a hint, divider or revealed fields only when they make the choice easier to understand.
- Use User view to try every option, including changing an answer after entering a follow-up value.
Give every item a stable ID
The Selection item ID is the stored value for that option. It must be unique within the choice component. Use a short, meaningful, machine-friendly name, such as email, telephone or other.
Choose the ID as though it were permanent. It can be used by conditions, Liquid templates, actions, exports and connected systems. Changing it later can leave an existing rule looking for a value that is no longer produced. If you must change an ID in a live service, first find and update every dependency, then test a new journey and a resumed draft.
| Prefer | Avoid |
|---|---|
representative |
option1 |
receive_updates |
a sentence with spaces |
other |
changing other to other_option after using it in rules |
The text people see can change for clarity without changing the stored ID. This is useful when you need to improve wording while keeping integrations stable.
Write useful selection text and hints
Selection item text is the label shown beside the option. Make choices distinct and mutually understandable. A person should not have to read all the options twice to know which one applies.
Use Hint text only for information that applies to that particular choice: a short example, a limitation, or an explanation of what happens next. Keep essential information in the main question or page content so that it is not missed by people choosing another option.
Selection text and hint text can use Liquid where a label genuinely needs to adapt to information already collected. Keep dynamic labels predictable: test when the referenced value is missing, blank, unusually long or in another language.
Reveal a small, related follow-up
Use Reveal fields when choosing one item should immediately show one or more closely related components on the same page. For example, choosing Other can reveal a field asking the person to describe the alternative.
flowchart TD
A[Contact preference] --> B{Selected option}
B -- Email --> C[Reveal email address]
B -- Telephone --> D[Reveal telephone number]
B -- No contact --> E[Show no follow-up]Attach the follow-up through the relevant selection item rather than building an extra visibility rule for a straightforward same-page relationship. This keeps the main answer and its dependent question together in the Builder.
Use a page condition instead when the answer controls a substantial section of the journey, several pages, or an action. A long hidden section below a choice is difficult to scan, test and maintain.
Check revealed fields carefully
- Make the revealed field required only when the controlling option is selected.
- Check that the revealed label makes sense directly after its option.
- Select an option, enter a value, then choose a different option. Confirm that downstream conditions and actions cannot use an irrelevant answer.
- Resume a draft and verify that the selected item and its follow-up display together.
Add a divider only when it clarifies a real alternative
Divider text below this selection item places a small separator after the item, commonly a word such as “or”. It is most useful when one option is an alternative route rather than another answer of equal weight.
Do not use dividers as decoration or between every option. If the choices need several dividers to make sense, regroup the question or split the decision into focused steps.
Example: choosing how to provide evidence
For a question asking how someone will provide a document, use stable IDs such as upload, send_later and other. Keep the labels human-readable, and reveal an explanation field only for other. A later condition can reliably check the item ID, while the wording remains free to improve.
Test checklist
- Every ID is unique within its choice component and describes a stable business meaning.
- Labels are clear without relying on their position in the list.
- Item hints add useful, option-specific help.
- Every revealed field appears for the right option and is validated only when visible.
- Changing an answer cannot leave a misleading value for a later template, condition or action.
- Dynamic labels have been checked with empty and long source values.