--- title: "Dynamic Lists Overview" slug: "dynamic-lists-overview" description: "Utilize Dynamic Lists to enhance forms with real-time data, ensuring accurate submissions and efficient filtering for user selections." updated: 2026-05-30T17:40:20Z published: 2026-05-30T17:40:20Z canonical: "www.civicplus.help/dynamic-lists-overview" --- > ## Documentation Index > Fetch the complete documentation index at: https://www.civicplus.help/llms.txt > Use this file to discover all available pages before exploring further. # Dynamic Lists Overview Dynamic Lists allow you to populate autocomplete, select, radio, or checkbox [form elements](/process-automation/docs/form-element-types) with re-useable options or dynamic data from your own API or URL. For example, you may have a list of supervisors that a user can select from a form. Instead of hard-coding those users into the form, you could feed this select box from an API that is designed to return the latest list of users. Additionally, this feature also allows you to have more control over the values being passed to your backend system when a form is submitted. For example, you may have a radio button set that allows a user to select “Pass”, “Fail”, or “N/A”, but your backend expects the values of these options to be “1”, “-1”, “0”, then instead of needing to rely on your form builders to get the values correct, you can instead feed them from your API. Dynamic Lists can also be used for calculations, check out the [Calculation article](/process-automation/docs/calculation-element) for more information. ## Using Dynamic Lists in a Form You can use the **List** tab to add Dynamic Lists to an autocomplete, select, radio, or checkbox [form element](/process-automation/docs/form-element-types). ![Form fields for playground selection with options for required and conditional display settings.](https://cdn.us.document360.io/17dc564a-8310-4f61-b929-1bd73b36e158/Images/Documentation/Dynamic%20List%20on%20Form%20Element%20-%20PADS.png?sv=2026-02-06&spr=https&st=2026-11-22T12%3A58%3A51Z&se=2026-11-22T13%3A58%3A51Z&sr=b&sp=r&sig=QFtzRaMpDWpaNKFK0JVBKZKMYQ0Cf1YqkFIvsuYAo4U%3D) --- ## Creating a Dynamic List ### Expected Payload Your API should return a payload in JSON format. It should be an array, with each item allowing four keys: - **Value:** the value that will be passed in the submission data (Required) - **Label:** the label that will be displayed to the user in the form (Required) - **Color:** set the color of your button when using radio buttons displayed as buttons (Optional) - **Attributes:** filter dynamic lists, they contain their own label and value (Optional) For more on attributes see the following [Filtering section](/process-automation/docs/dynamic-lists-overview#filtering). ### Dynamic List JSON Example ```plaintext [   {      "value":"1",      "label":"Pass",      "colour":"#00DD00"   },   {      "value":"0",      "label":"Fail",      "colour":"#DD0000"   },   {      "value":"-1",      "label":"N/A",      "colour":"#CCCCCC"   } ] ``` --- ## Filtering Dynamic Lists can also contain attributes. These are used to filter the list based on the inputs of other elements. For example, I have a list of users and each of those users has a supervisor. I am able to limit the list by selecting a specific supervisor. ### Expected Attributes - **Label:** the displayed name for the attributes in the forms builder (Required) - **Value:** the value that will be filtered by a separate configured dynamic list (Required) The dynamic list will look like this: ```plaintext    {      value: 'ASmith',      label: 'Alex Smith',      attributes: [        {          'label': supervisor,          'value': 'Lisa Daniels'        },        {          'label': position,          'value': 'Marketing'        }      ]    },    {        value: 'JCauthen',        label: 'Mary Johnson',        attributes: [          {            'label': supervisor,            'value': 'Lisa Daniels'          },          {            'label': position,            'value': 'Operations'          }        ]    },    {        value: 'AWilliams',        label: 'Alice Williams',        attributes: [          {            'label': supervisor,            'value': 'Liam Jackson'          },          {            'label': position,            'value': 'Sales'          }        ]    },    {        value: 'JDavis',        label: 'Jacob Davis',        attributes: [          {            'label': supervisor,            'value': 'Liam Jackson'          },          {            'label': position,            'value': 'Marketing'          }        ]    } ``` Now when a supervisor is selected, the list will be filtered so that it only includes the users with that supervisor. ![Dropdown menus for selecting supervisors and users in a form interface.](https://cdn.us.document360.io/17dc564a-8310-4f61-b929-1bd73b36e158/Images/Documentation/Dynamic%20List%20Filtering%20-%20PADS.png?sv=2026-02-06&spr=https&st=2026-11-22T12%3A58%3A51Z&se=2026-11-22T13%3A58%3A51Z&sr=b&sp=r&sig=81bvUx3MqOf%2Bjd2xM88Q4cHT2qm2NpODxaMea1RTF0Q%3D) When no supervisor is selected the entire list is shown. When Supervisor Lisa Daniels is selected the list is filtered to only display users assigned to Lisa. --- ## Multiple Attributes Attributes are an array, meaning you can have multiple attributes for the same option. When adding multiple attributes the options will display if **any** of the attributes are met. So, if we search on the position attribute to each of our users as well as the supervisor, we will get the users who have any of those attributes. [![Dropdown menu for selecting supervisor, position, and users in a marketing context.](https://cdn.us.document360.io/17dc564a-8310-4f61-b929-1bd73b36e158/Images/Documentation/Dynamic%20List%20Multiple%20Attributes%20-%20PADS.png?sv=2026-02-06&spr=https&st=2026-11-22T12%3A58%3A51Z&se=2026-11-22T13%3A58%3A51Z&sr=b&sp=r&sig=DAftLeT9PJ7pCtYXWTNUX3Im2AcXfIc83Pgagw7NWDo%3D)](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/42019639744/original/E4En4sEh7nFXN3v_lSummWAJQL9kTacgNg.png?1555559213) As you can see, only Alex and Mary have Lisa as their supervisor, but Alex and Jacob are in the Marketing team, so all three are being displayed. ### Code Examples You can download code examples from our GitHub repo. This code is standard NodeJS, and can be used in a CivicPlus Hosted API, or in your own code to get you started: - [GitHub: Dynamic Form Elements](https://github.com/blinkmobile/server-cli/tree/master/examples/dynamic-form-element-options) --- ## Setting Attributes When implementing attributes, you will assign the element which will be used as the filter. --- ## Testing Once you’ve set up your endpoint in the Process Automation and Digital Services Console, you can click on the Test button. This will test your endpoint to ensure it is returning data in the expected format. If any errors are found, they’ll be displayed to you for further debugging. If the test is successful, it will return the number of records found and allow you to view the response details. ![Table displaying employee details including names, supervisors, and positions in various departments.](https://cdn.us.document360.io/17dc564a-8310-4f61-b929-1bd73b36e158/Images/Documentation/Dynamic%20List%20Test%20Successful%20-%20PADS.png?sv=2026-02-06&spr=https&st=2026-11-22T12%3A58%3A51Z&se=2026-11-22T13%3A58%3A51Z&sr=b&sp=r&sig=%2BfwDkWRO1tekiNFs1U0DQMxtGCoXmSMGfbQi8ED4Zpo%3D) --- ## Offline Usage Your app users can often be in either intermittent coverage or no coverage at all. In these cases, your app will continue to operate as usual, using a cached version of your dynamic lists results. When the app is first opened, all dynamic lists in all of your forms will be automatically cached. The app will work in a “connected first” assumption, where if your user has an internet connection, then your lists will be populated directly from your API. If, however, they have no internet connection, the cached version of your dynamic lists will be displayed. Application Programming Interface. A set of rules that allows programmers to develop software for a particular operating system without having to be completely familiar with that operating system. Uniform Resource Locator JavaScript Object Notation. ## Related - [Create a Dynamic List](/create-a-dynamic-list.md) - [Create and Manage Forms](/create-and-manage-forms.md)