Function

a!dropdownField( label, labelPosition, instructions, required, disabled, choiceLabels, choiceValues, placeholder, value, validations, saveInto, validationGroup, requiredMessage, helpTooltip, accessibilityText, showWhen, searchDisplay, data, sort )

Displays a list of choices for the user to select one item and saves a value based on the selected choice.

Parameters

Usage considerations

When to use a dropdown

There are multiple selection components you can use to display options in an interface. As a best practice, you should use a dropdown component when there are only a small set of options.

If there aren't many options and users would benefit from easily seeing them all at once, consider using radio buttons.

If there are a large set of options, consider using a picker component. The picker search runs server-side and the performance cost of loading options happens while the user is searching. This may lead to better performance than a dropdown if you have a large set of options.

If the user may select none, one, or many of the options, use either the checkbox component or a multiple dropdown component.

Using the choiceLabels and choiceValues parameters

When you select a record type in design mode, the Choice Labels and Choice Values are automatically populated with record field references. By default, the labels will be the first text field from the record type, and the values will be the primary key field.

If you select the Other option, you need to configure these parameters manually. As you configure them, keep the following points in mind:

• Choices display in the order defined in the Choice Labels.
• The Choice Labels cannot be null.
• Choice Values cannot contain nulls or duplicate values.
• The Choice Labels list and Choice Values list must be the same length.

These rules also apply when using data from a record type, except that choice order is determined by any sorting applied in the Sort section. If no sorting rules are configured, the choices are displayed in ascending order of the Choice Values field.

Using the placeholder parameter

To allow users on web to clear the selected value, text must be specified for the placeholder parameter. Users can always clear the value on the Appian for Mobile application.

Passing a null value to the dropdown's Selected Value parameter causes the placeholder text to appear selected. The Placeholder and Selected Value parameter cannot both be null.

Row limit for records-powered components

Interface components that use a record type as the data source are known as records-powered components.

Records-powered components can display a maximum of 5,000 rows. As a best practice, you should not display all 5,000 rows in a component since it may impact performance.

Examples

To experiment with examples, copy and paste the expression into an interface object.

Record type object references are specific to each environment. If you copy and paste the example with record field references into your interface, it will not evaluate. Use that example as a reference only.

Dropdown with choices from a record type

In this example, the component's choices are retrieved from a reference record type that contains the full names and abbreviations of US states. choiceLabels uses the name field and the corresponding choiceValues are set using the record type's primary key field, id.

1
2
3
4
5
6
7
8
9
a!dropdownField(
  data: recordType!AT State,
  choiceLabels: recordType!AT State.fields.name,
  choiceValues: recordType!AT State.fields.id,
  label: "State",
  placeholder: "Select a state",
  value: ri!record[recordType!AT Customer.relationships.address.fields.stateId],
  saveInto: ri!record[recordType!AT Customer.relationships.address.fields.stateId],
)

Dropdown with the first choice selected by default and search on auto

Since the searchDisplay parameter is set to AUTO and the number of choiceValues is less than 12, no search box will be displayed.

Use the interactive editor below to test out your code:

Since the searchDisplay parameter is set to AUTO and the number of choiceValues is more than 11, a search box will be displayed.

Use the interactive editor below to test out your code:

Dropdown with no choice selected by default and search on

Since the searchDisplay parameter is set to ON, even though the number of choiceValues is less than 12, a search box will be displayed.

Use the interactive editor below to test out your code:

Feature compatibility

Old versions

There are older versions of this interface component. You can identify older versions by looking at the name to see if there is a version suffix. If you are using an old version, be sure to refer to the corresponding documentation from the list below.

To learn more about how Appian handles this kind of versioning, see the Function and Component Versions page.

Related Patterns

The following patterns include usage of the Dropdown Component.

• Add Validations to an Inline Editable Grid (Validation, Grids, Looping): Allows the user to change data directly in a grid, and validate a various entries.

• Add, Edit, and Remove Data in an Inline Editable Grid (Grids, Looping): Allow the user to change data directly in an inline editable grid.

• Conditionally Hide a Column in a Grid (Grids, Conditional Display): Conditionally hide a column in a read-only grid when all data for that column is a specific value.

• Configure Buttons with Conditional Requiredness (Validation): Present two buttons to the end user and only make certain fields required if the user clicks a particular button

• Configure Cascading Dropdowns (Conditional Display, Choice Components): Show different dropdown options depending on the user selection.

• Configure a Dropdown Field to Save a CDT (Choice Components): When using a dropdown to select values from the database, or generally from an array of CDT values, configure it to save the entire CDT value rather than just a single field.

• Configure a Dropdown with an Extra Option for Other (Choice Components): Show a dropdown that has an "Other" option at the end of the list of choices. If the user selects "Other", show a required text field.

• Configure an Array Picker with a Show All Option (Pickers): Allow users to choose from a long text array using an autocompleting picker, but also allow them to see the entire choice set using a dropdown.

• Display Multiple Files in a Grid (Document Management, Grids): Show a dynamic number of files in a grid and edit certain file attributes.

• Document List (Documents): Use the document list items pattern to display a list of documents that can be searched and filtered. This pattern uses a combination of cards and rich text to show an easy to navigate list of documents of different types.

• Dynamically Show Sales by Product Category Compared to Total Sales (Records, Reports, Charts, Filtering): This pattern illustrates how to create an area chart that dynamically displays sales generated by product category compared to total sales.

• Filter the Data in a Grid (Grids, Filtering, Records): Configure a user filter for your read-only grid that uses a record type as the data source. When the user selects a value to filter by, update the grid to show the result.

• Save a User's Report Filters to a Data Store Entity (Grids, Smart Services, Filtering, Reports): Allow a user to save their preferred filter on a report and automatically load it when they revisit the report later.

• Searching on Multiple Columns (Grids, Filtering, Reports): Display a grid populated based on search criteria specified by end users.

• Track Adds and Deletes in Inline Editable Grid (Grids): In an inline editable grid, track the employees that are added for further processing in the next process steps.

• Update an Entity-Backed Record from its Summary View (Records, Smart Services): Enable users to make quick changes to a record by updating it right from a record view.

• Use Links in a Grid to Show More Details and Edit Data (Grids): Allow end users to click a link in a read-only grid to view the details for the row, and make changes to the data. The data available for editing may include more fields than are displayed in the grid.

• Use Selection For Bulk Actions in an Inline Editable Grid (Grids): Allow the user to edit data inline in a grid one field at a time, or in bulk using selection.

• Use Validation Groups for Buttons with Multiple Validation Rules (Validation): Present two buttons to the end user that, based on the selection, will validate only after a particular button is clicked.

• Use a Filter to Adjust Chart Reference Lines (Filtering, Charts): Using a dropdown, filter the results of a data set while also adjusting a chart reference line.

• Year-Over-Year Report (Charts, Reports, Formatting): This is a feature-rich, interactive report for sales and profits by products over select periods of time.