Dropdown Component

Function

Copy link to clipboard

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

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

Parameters

Copy link to clipboard

Usage considerations

Copy link to clipboard

When to use a dropdown

Copy link to clipboard

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

Copy link to clipboard

When configuring the Choice Labels and Choice Values parameters, keep the following in mind:

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

When you select Record Type as the data source, 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.

You can format and display multiple record fields in the Choice Labels parameter using fv!data and a record field reference. For example, if you want to display a list of US cities with their states in parentheses, you could use the following expression:

1
choiceLabels: fv!data[recordType!Location.fields.city] & " (" & fv!data[recordType!Location.fields.state] & ")"
Copy

This would display choice labels as:

1
2
3
4
5
New York City (New York)
Los Angeles (California)
Chicago (Illinois)
Houston (Texas)
Phoenix (Arizona)
Copy

Sort choices

Copy link to clipboard

The way you sort the choices depends on the source of the component. If no sort is applied, the labels will appear in the order they're provided.

When you select Record Type as the data source:

• The choice order is determined by the Sort parameter.

• You can automatically sort by the values configured in the Choice Labels or Choice Values parameters by using "choiceLabels" or "choiceValues" in the a!sortInfo() function.

  For example, a!sortInfo(field: “choiceLabels”, ascending: true) would automatically sort the choices by the values in the Choice Labels parameter.

When you select Other as the data source:

• The choices display in the order defined in the Choice Labels.

Using the placeholder parameter

Copy link to clipboard

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

Copy link to clipboard

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

Copy link to clipboard

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

Copy link to clipboard

In this example, the component's choices are retrieved from a reference record type that contains the full names and abbreviations of US states.

The choiceLabels parameter references the name field and the name_short field to display the name of each state and the state's abbreviation in parentheses. The choiceValues are set using the record type's primary key field, id.

1
2
3
4
5
6
7
8
9
10
11
12
a!dropdownField(
  data: recordType!AT State,
  choiceLabels: fv!data[recordType!AT State.fields.name] & " (" & fv!data[recordType!AT State.fields.name_short] & ")",
  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],
  sort: a!sortInfo(
    field: "choiceLabels",
    ascending: true)
)
Copy

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

Copy link to clipboard

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

Copy link to clipboard

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

Copy link to clipboard

Old versions

Copy link to clipboard

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

Copy link to clipboard

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.

Feedback

Copy link to clipboard