The DROPDOWN component provides a selection list where users can choose one option from a predefined list or dynamically fetched options.
🛝 Use the Dynamic Form Playground to see the Dropdown component in action and try out different configurations
| Property | Type | Required | Description |
|---|---|---|---|
type | 'DROPDOWN' | Yes | Specifies the field type as DROPDOWN. |
id | string | Yes | Unique identifier for the field. The field's value is stored in the form state under this key. |
renderName | string | No | Optional name added as data-render-name attribute to locate the rendered element in the DOM. |
label | string | Yes | Label text displayed above the field. Supports translation and string interpolation. |
value | string | number | boolean or (string | number | boolean)[] | No | The initially selected option value(s). For single-select (multiSelect omitted or false): a single option value. For multi-select (multiSelect: true): an array of option values. Each entry must match the value of one of the configured options. |
hint | string | No | Additional hint text displayed below the field. |
note | string | No | Informational note displayed when there are no errors. |
infoIcon | DfInfoIconConfig | No | Info icon with popover. Object with popoverText (string, required) and popoverDirection ('top', 'bottom', 'left', 'right'). |
validators | array | No | Validation rules for the field. Common type: REQUIRED. The validator has type and optional errorMessage. |
testId | string | No | Test identifier for automated testing. Set as data-testid attribute. |
acl | array | No | Access control rules for field visibility/editability. Each rule has state ('hidden', 'readonly', 'disabled', 'visible', 'editable') and optional condition (Filtrex expression). |
columnSpan | number | No | Number of columns to span (1-12) in CUSTOM_COLUMN layout. Default: 12 (full width). See Overriding the number of grid columns when using --df-custom-columns. |
spacing | string | No | Margin spacing before next field: 'NONE' (0px), 'XS' (8px), 'S' (16px), 'M' (24px), 'L' (32px), 'XL' (40px), 'XXL' (48px). |
| Property | Type | Required | Description |
|---|---|---|---|
multiSelect | boolean | Yes | Whether multiple options can be selected at the same time. When false or omitted, only a single option can be selected (FormControl value is a single value).When true, multiple options can be selected (FormControl value is an array). |
options | DfOptions[] | string | Yes | The options property can take one of two forms:1. A hardcoded array of objects for direct display in a dropdown menu. Each object must have a label to display and a corresponding value.2. A string that represents an expression. This expression is used by an option provider service to dynamically fetch the dropdown options. See also DfOptions |
autoPrefill | boolean | No | If there is only one option, pre-fill the field. Default is not to prefill. |
clearOptionLabel | string | No | The label for the option to clear the currently selected value. If this label is set, the clear option will be displayed when the dropdown has a value. It's translatable by default and supports string interpolation. |
filterPlaceholder | string | No | Placeholder text for the dropdown filter field. This is what is displayed when no filter expression has been entered yet. |
inputPrefix | string | No | Prefix text to place at the start of this field's input. It's translatable by default and supports string interpolation. |
inputSuffix | string | No | Suffix text to place at the end of this field's input. It's translatable by default and supports string interpolation. |
layout | object | No | The layout of the field. See also Layout Properties |
optionalLabel | string | No | Text that is additionally displayed in the label if the field is not mandatory. |
placeholder | string | No | Placeholder to be displayed in the field when the input is empty. It's translatable by default and supports string interpolation. |
showFilter | boolean | No | Whether the dropdown should be filterable or not. If set and true the dropdown values can be filtered.If not set or false, the dropdown will not be filterable. |
| Property | Type | Required | Description |
|---|---|---|---|
label | string | Yes | The label to display for the list |
value | string | number | boolean | Yes | The value of the option |
testId | string | No | The test id of the option used for automated tools, like cypress to find the componentand made independent of other config changes. If implemented, the value should be the following data-testid=VALUE_HEREwith the testid in lowercase. |
| Property | Type | Required | Description |
|---|---|---|---|
centerAlignInRetail | boolean | No | Controls the field alignment for "CUSTOM_COLUMN" layout in retail journeys. Set to true to center-align the field. Defaults to left alignment.Ignored in expert journeys and other pre-defined layouts, which always use left alignment. |
{
"id": "country",
"type": "DROPDOWN",
"label": "Country",
"placeholder": "Select your country",
"options": [
{
"label": "Germany",
"value": "DE"
},
{
"label": "Austria",
"value": "AT"
},
{
"label": "Switzerland",
"value": "CH"
}
],
"validators": [
{
"type": "REQUIRED"
}
]
}{
"id": "city",
"type": "DROPDOWN",
"label": "City",
"placeholder": "Select a city",
"showFilter": true,
"filterPlaceholder": "Search for a city...",
"clearOptionLabel": "Clear selection",
"options": [
{
"label": "Munich",
"value": "munich"
},
{
"label": "Berlin",
"value": "berlin"
},
{
"label": "Hamburg",
"value": "hamburg"
}
]
}{
"id": "productType",
"type": "DROPDOWN",
"label": "Product Type",
"placeholder": "Select product type",
"options": "$.availableProducts",
"autoPrefill": true
}For complete API documentation, see:
For Aquila component documentation and design guidelines, see Dropdown - Aquila Design System.