Dropdowns & Selects

Choosing the Right Component

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.

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

Appearance Properties

Events, Methods & State

Single-select Dropdown Field (inside a Form)

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

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 — the field to display as each option's label.

• Search Type — Contains or Starts With.

• Search By — Label only, or Label and Value.

• Allow Custom Value add-on — lets users type a value not in the list.

Multi-select Dropdown Field (inside a Form)

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

Multi-select Extras

• Select All — appears at the top of the list; selects every visible option.

• Allow Custom Value add-on — users can type a custom value not in the defined list.

• Search — built-in search over options; configure search type (Contains/Starts With) and whether to search label only or label + 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

State & Events

Category Filter Block

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.

Content Properties

Exposed State

Frequently Asked Questions

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?

For a form field dropdown, set Options Source to Data Source and bind a query or API connector. Map the Label Field and Value Field to the appropriate columns. For a standalone Single Select block, set Options Type to LOOKUP and bind the data array. Both approaches update the option list reactively when the data 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 mode to DYNAMIC and bind a query to each level. When the user selects an option at level N, the block fires a selection event that you can use to re-query the data for level N+1 (filtered by the parent selection). In STATIC mode, provide the full nested structure upfront as a JSON array with children arrays.

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

The Category Filter block exposes a structured filter object at {{ id.filter }} containing all the user's active selections as key-value pairs grouped by category. Pass this object directly to a query's filter parameter — most UnifyApps data sources and API connectors accept this filter format natively. The filter updates reactively as the user adds or removes selections, so any bound query re-runs automatically.

Step-by-Step Examples

Status Filter Driving a Table

1. Drop a Single Select block above a data table.

2. Add options: All, Active, Inactive.

3. In the table's data source, add a filter condition: status equals {{ singleSelect1.value }}.

4. The table re-queries whenever the user changes the selection.

Multi-select Tags in a Form

1. Add a Multi-select Dropdown field to your Form block. Field key: tags.

2. Add options: Frontend, Backend, Design, QA.

3. Leave Is Optional off to require at least one tag.

4. On submit, {{ form1.data.tags }} is an array like ["frontend", "design"].

Cascader for Region > City Selection

1. Drop a Cascader block.

2. Switch to Mapped type and bind Source to your regions data source.

3. Map Label → regionName, Value → regionId, Nested Options → cities.

4. For the nested level, map Label → cityName, Value → cityId.

5. Read the selected city with {{ cascader1.value }}.

Category Filter Narrowing a Product Catalog

1. Drop a Category Filter block beside your product table.

2. In Data Sources, select your products data source.

3. In the products data source, bind the filter parameter to {{ categoryFilter1.filter }}.

4. The table re-queries as users check/uncheck category facets.