When should I use a Single Select block vs. a Single-select Dropdown form field?

Use the standalone Single Select block when the selection drives page behavior immediately — filtering a table, switching a panel, or controlling other UI state. Its value is available via {{ id.value }} on every change. Use the Single-select Dropdown form field when the selection is part of a data-entry form that gets submitted as a unit, since it participates in form validation and the submit payload.

How do I load dropdown options from a database table or API?

Set the options type to Mapped. This works the same way on a form field dropdown (the Type setting) and on a standalone Single Select block. Then pick a Source, such as an object's records or a data source, and choose the Label field to show for each option. The option list updates when the source refreshes.

What does "Allow Custom Value" do on the Single-select Dropdown form field?

When the Allow Custom Value add-on is enabled, the user can type a value that doesn't exist in the predefined option list and submit that as the field's value. This is useful for fields where you want to suggest common options but not restrict the user to them. Without this add-on, only predefined options can be selected.

How does the Cascader block handle dynamic data for its nested options?

Set the Cascader's type to Mapped and bind one hierarchical Source list. One mapping (Label, Value, Nested Options) applies at every level, so every level of the data must use the same property names. There is no per-level query. In Manual mode, you enter the full nested option list in the builder.

What is exposed in {{ categoryFilter.filter }} and how do I use it?

The Category Filter block exposes {{ id.filter }}, a UnifyApps filter condition built from all the user's active selections. Pass it whole to a UnifyApps data source's filter input. The filter updates as the user adds or removes selections, so any bound query re-runs automatically.

Overview

Dropdowns let users pick from a list of options without taking up much space on the page. UnifyApps offers them in two forms: standalone blocks, which update page state the moment the selection changes, and Form fields, whose values are validated and submitted with the rest of the form.

This page covers the Single Select block, the Single-select and Multi-select Dropdown fields, the Cascader block for choosing from a hierarchy, and the Category Filter block for faceted filtering. Start with the table below to pick the right one.

Choosing the Right Component

Scenario	Component
Standalone dropdown that drives page state immediately on change	Single Select block
Dropdown inside a form, single choice, submitted with the form	Single-select Dropdown field (Form)
Dropdown inside a form, multiple choices, submitted with the form	Multi-select Dropdown field (Form)
Pick one item from a multi-level hierarchy (categories, regions)	Cascader block
Faceted filter panel for narrowing a data list	Category Filter block

Single Select Block (Standalone)

A single-choice dropdown for standalone use. Options come from a static list or a data lookup. Users can type to filter choices. The block stores the chosen option's value string as state, readable with {{ id.value }}. On mobile apps the list can open as a bottom sheet or dropdown.

unify-applications-dropdowns-and-selects-01-single-select-block.png

When to Use

Use as a standalone selector or filter that drives page state the moment it changes — e.g. a status filter above a table.
For form submission, use the Single-select Dropdown field inside a Form block instead.
Prefer over a Radio group when the option list is long or should stay collapsed.

Content Properties

Property	Type	Default	Description
Label	string	—	Text shown above the field.
Options	Manual or Mapped	Manual	Opens the options panel. Set Type to Manual to enter options inline, or to Mapped to read them from a Source, such as an object's records or a data source.
Help Text	string	—	Additional information below the field.
Description	string	—	Secondary line under the label.
Placeholder	string	"Select an option"	Text shown when nothing is selected.
Default value	string (bindable)	—	Selection on initial render. Must match an option value. Dynamic bindings update the selection.
Slots → Footer	block	—	Block rendered at the bottom of the open list, commonly a "Create new" button.

Appearance Properties

Property	Type	Default	Description
Container	Bottom Sheet or Dropdown	Bottom Sheet	How options open. Shown for mobile apps only.
Start Icon	icon name	—	Icon shown at the start of the field.
Size	sm or md	md	Field height.
Styles	style set	—	Width, min/max width, color, stroke, radius.
Disabled	condition	—	Disables interaction while the condition is true.
Visibility	condition	—	Shows or hides the block.
Variant	Ghost, Outlined or Solid	Outlined	Visual style of the field.

Events, Methods & State

Item	Type	Description
On Change	event	Fires when the selection changes. Payload: `value`.
`{{ id.value }}`	string state	The currently selected option's value string.
Set Value	method	Sets the selection programmatically to an option value.
Reset	method	Clears the selection or resets it to the default.

Note: Set Value and Reset change {{ id.value }} silently and do not fire On Change. Run any dependent refresh, such as re-querying a data source, in the same action.

A dropdown inside a Form block for picking exactly one option. The field's value is that option's value string. Participates in form validation, required checks, and the submit payload.

Properties

Property	Type	Default	Description
`Label`	string	—	Display label above the field.
`Default Value`	string (bindable)	—	Initial selection. Dynamic bindings update on change.
`Placeholder`	string	—	Text shown while nothing is selected.
`Field Key`	string	—	Unique key to read the value: `{{ form1.data.fieldKey }}`.
`Type`	`Manual \| Mapped`	`Manual`	Options listed manually, or mapped from a data source.
`Is optional`	boolean	true	Turn off to make selection required.
`Disabled / Read Only`	condition	—	Disable or lock the field based on a condition.

Option Configuration (Manual Mode)

Each option has:

Label — what the user sees in the list.
Value — unique string stored in the form data.
Icon, Color, Caption, Badge — optional visual enhancements.
Disabled condition — condition under which this specific option is greyed out.
Visibility condition — condition under which this option is hidden from the list.

Option Configuration (Mapped/Lookup Mode)

Source — the object or data source to pull records from.
Label field — for an object source, the field to display as each option's label.
Data Source and Mapped Options — for a data source, pick the data source, then map Label (what the user sees) and Value (what is stored in the form data). You can also map Description, Icon, Color and more. See Dropdown Data Source Options for the full list.
Search Type — Contains or Starts With.
Search By — Label, or Label & Value.
Allow Custom Value add-on — lets users type a value not in the list.

A dropdown for picking several options. The field's value is an array of the selected options' value strings. Supports select-all, typed custom values, and data-source options with search.

Properties

Property	Type	Default	Description
`Label`	string	—	Display label above the field.
`Default Value`	array (bindable)	—	Initial selection, an array of value strings. Dynamic bindings update the field.
`Placeholder`	string	—	Text shown while nothing is selected.
`Field Key`	string	—	Unique key to read the value array: `{{ form1.data.fieldKey }}`.
`Type`	`Manual \| Mapped`	`Manual`	Options listed manually, or mapped from a data source.
`Is optional`	boolean	true	Turn off to require at least one selection.

Multi-select Extras

Select All: turn on Enable select all options to show a Select All entry at the top of the list. It selects every visible option.
Custom values: turn on Allow custom value to let users type a value that isn't in the list.
Search: built-in search over options. Set the search type (Contains or Starts With) and whether to search the label only or the label and value.

Cascader Block

The Cascader block is a dropdown for choosing one value from a hierarchy — categories with sub-categories, departments with roles, regions with cities. Opening it shows the tree as side-by-side columns the user drills through, and typing searches every level at once, showing full paths like "Business / Finance / Chloe".

When to Use

Pick one item from a multi-level hierarchy without showing the whole tree at once.
Populate the hierarchy from an API using the Mapped type.
For a flat list of choices, use a select field. For multi-select across a tree, this block is not suitable — it selects exactly one leaf.

Content Properties

Property	Type	Default	Description
`type`	`STATIC \| DYNAMIC`	`STATIC`	Manual nested list or Mapped hierarchical data.
`options`	nested option list	Sample org tree	The hierarchy. Each option has Label, Value, and optional child options. Only in Manual mode.
`mappedOptions`	data binding + mappings	—	One Source list and one mapping for Label, Value and Nested Options. The same mapping applies at every level, so every level of the data must use the same property names. Only in Mapped mode.
`placeholder`	string	"Select"	Text shown when nothing is selected.
`initialValue`	string (bindable)	—	Shown as Default value. Sets the selection on initial render. Dynamic bindings update the selection.

State & Events

Item	Description
`{{ id.selectedValue }}`	The selected option's value (the leaf value). `null` until a leaf is picked.
`{{ id.selectedPath }}`	The full path from the root to the selected leaf, as an array of `{ value, label }`, one entry per level. `null` until a leaf is picked.
On Select Option	Fires when the user picks a leaf or clears the field. Read the selection from `{{ id.selectedValue }}` and `{{ id.selectedPath }}`.

The Category Filter block renders a faceted filter panel — the "refine by" sidebar familiar from e-commerce catalogs. It exposes the user's combined selections as one filter object other blocks and data sources can consume. On desktop it renders as a vertical sidebar; on mobile and tablet it switches to a horizontal arrangement.

When to Use

Let users narrow a catalog or list by attributes — brand, price range, status.
Drive a data source's filtering: bind the query's filter input to {{ id.filter }}.
For free-form condition building rather than category facets, use the Filters block instead. See Sort and Filter.

Content Properties

Property	Type	Default	Description
Data	data binding (facet list)	—	Facet definitions bound directly: a list of field definitions in the same shape as the `aggregationFields` a data source returns, one entry per filterable field. When set, this list is used as-is and Data Sources is ignored.
Data Sources	data source multi-select	none	Page data sources whose responses supply the filterable facets automatically.
Interactions	event list	—	On Change fires when the user changes any selection, including clearing it from the panel. It has no payload. Read the combined filter from `{{ id.filter }}`.

Exposed State

State Key	Description
`{{ id.filter }}`	A UnifyApps filter condition built from all the user's category selections. Pass it whole to a UnifyApps data source's filter input.

Methods

Method	Effect
Clear Filters	Empties `{{ id.filter }}`. It does not fire On Change, so re-run the data source in the same action.

Step-by-Step Examples

Status Filter Driving a Table

Drop a Single Select block above a data table.
Add options: Active, Inactive.
In the table's data source, add a filter condition: status equals {{ singleSelect1.value }}.
The table re-queries whenever the user changes the selection. Clear the selection to show every row.

Multi-select Tags in a Form

Add a Multi-select Dropdown field to your Form block. Field key: tags.
Add four options and set each option's Label and Value: Frontend / frontend, Backend / backend, Design / design, QA / qa.
Turn Is optional off to require at least one tag.
On submit, {{ form1.data.tags }} is an array of the selected values, like ["frontend", "design"].

Cascader for Region > City Selection

Drop a Cascader block.
Switch to Mapped type and bind Source to your locations data source. Every level must use the same property names, for example name, code and children for both regions and cities. Reshape the data first if it doesn't.
Map Label → name, Value → code, Nested Options → children. This one mapping applies at every level.
Read the selected city with {{ cascader1.selectedValue }}.

Drop a Category Filter block beside your product table.
In Data Sources, select your products data source.
In the products data source, bind the filter parameter to {{ categoryFilter1.filter }}.
The table re-queries as users check/uncheck category facets.

Dropdowns & Selects

Overview

Choosing the Right Component

Single Select Block (Standalone)

When to Use

Content Properties

Appearance Properties

Events, Methods & State

Properties

Option Configuration (Manual Mode)

Option Configuration (Mapped/Lookup Mode)

Properties

Multi-select Extras

Cascader Block

When to Use

Content Properties

State & Events

Category Filter Block

When to Use

Content Properties

Exposed State

Methods

Step-by-Step Examples

Status Filter Driving a Table

Multi-select Tags in a Form

Cascader for Region > City Selection

Category Filter Narrowing a Product Catalog

Dropdowns & Selects

Overview

Choosing the Right Component

Single Select Block (Standalone)

When to Use

Content Properties

Appearance Properties

Events, Methods & State

Single-select Dropdown Field (inside a Form)

Properties

Option Configuration (Manual Mode)

Option Configuration (Mapped/Lookup Mode)

Multi-select Dropdown Field (inside a Form)

Properties

Multi-select Extras

Cascader Block

When to Use

Content Properties

State & Events

Category Filter Block

When to Use

Content Properties

Exposed State

Methods

Step-by-Step Examples

Status Filter Driving a Table

Multi-select Tags in a Form

Cascader for Region > City Selection

Category Filter Narrowing a Product Catalog