Filter Listing

Audience: Low-code Engineers

Skill Prerequisites: Actions, Listings, Tokens

Changes the filters, search, sorting or paging of a Listing module on the same page, without reloading the page. Use it to build your own search form for a listing.

The action writes the new settings into the page URL as query string parameters. The listing reads the URL and reloads its data.

Typical Use Cases

• Build a search form next to a listing, for example to pick a status and a category
• Show only the rows for a value the user picked, such as a customer or a project
• Jump to the first page or change the sort order from a form button

Don't use it to

• Just reload a listing. Use Refresh Listing instead.
• Reload the listing that ran the button. Use Datasource Refresh instead.
• Filter a listing on another page. The listing must be on the same page.
• Filter a listing from an API endpoint or a scheduled task. It's not available there.

Related Actions

Action Name	Description
Refresh Listing	Reloads a listing without changing its filters.
Datasource Refresh	Reloads the listing that ran the button.
Get Data Query	Stores the listing's query and the filters the user applied in tokens.
Redirect to URL	Sends the user to another page, for example a listing page with filters in the URL.

Input Parameter Reference

Parameter	Description	Supports Tokens	Default	Required
Action Grid Module	The Listing module to filter. It must be on the same page.	No	empty	Yes
Current Page	The page number to show, for example 1. Leave it empty to keep the current page.	Yes	empty	No
Page Size	The number of rows per page, for example 50. Leave it empty to keep the current page size.	Yes	empty	No
Sort By	The name of the field to sort by. The listing sorts by one field at a time. Leave it empty to keep the current sorting.	Yes	empty	No
Sort Descending	Sorts from high to low. Only used when Sort By has a value.	No	false	No
Search Terms	The text to search for, like typing it in the listing's search box. If it's empty, the current search is cleared.	Yes	empty	No
Filters	A list of filters. Field Name is the name of a listing field, Value is the value to filter by, for example Status and [Status].	Value only	empty	No
Replace Filters	Removes the current filters before the new ones are added. When it's off, the new filters are merged with the ones already applied. A filter on the same field is replaced.	No	false	No
Additional Data	Extra values added to the page URL as query string parameters, as Name and Value pairs. The listing can use them like any other query string value, for example in its data source.	Value only	empty	No

How it works

1. The action reads the current page URL and adds the new parameters for the selected listing. Parameters that you leave empty keep their current value, except Search Terms.
2. The new URL is pushed to the browser without reloading the page.
3. The listing sees the URL change and reloads its data with the new filters.

Because the settings are in the URL, the user can bookmark or share the filtered listing, and the browser's back button goes back to the previous filters.

Considerations

• Turn on Sync with URL. The listing reacts to the new URL only when Sync with URL is on in its settings. See Sync with URL.
• Make the fields filterable. A filter only applies to a listing field that is marked as filterable. Use the field's name, not its title.
• Current listing views. The page, page size, sorting and search are written in the query string format of the legacy listing views. In PAA 1.28 the current views only pick up the Filters. If you need the other settings, test them on your listing first.
• Replace Filters and filters the user picked. Replace Filters removes filters in the format this action writes. With the current views, filters the user picked in the listing may still stay applied.
• Same page only. If the listing isn't on the current page, the action fails and the user sees There was an error filtering.
• Empty search clears the search. Leave Search Terms empty only when you want to remove the current search. To keep it, pass it back, for example from a form field.
• Field names are plain text. The Field Name of a filter and the Name of additional data aren't tokenized. Only the values are.
• Where it's available. The action is meant for forms and listing buttons. It's not available in API endpoints or scheduled tasks. The config also defines Store Absolute URL and Store Relative URL, but in PAA 1.28 they're only shown where the action isn't available.
• Conditions. To filter only in some cases, give it a condition, for example "[Category]" != "". See Common Parameters.

Examples

tip

To understand how to use the below examples, please see Running Examples.

1. Filter a listing from a search form

Add this action to a "Search" button of a form with Status and Category fields. It replaces the filters of the Listing module 1234 on the same page with the values the user picked.

{
    "Title": "Filter Listing",
    "ActionType": "FilterActionGrid",
    "Description": "Filter orders by status and category",
    "Parameters": {
        "ActionGridModule": "1234",
        "Filters": [
            {
                "name": "Status",
                "value": "[Status]"
            },
            {
                "name": "Category",
                "value": "[Category]"
            }
        ],
        "ReplaceFilters": true
    }
}

2. Show the latest orders first

This action goes back to the first page of the Listing module 1234 and sorts it by CreatedOn, newest first. It keeps the current search by passing back the SearchText form field.

{
    "Title": "Filter Listing",
    "ActionType": "FilterActionGrid",
    "Description": "Sort orders by date, newest first",
    "Parameters": {
        "ActionGridModule": "1234",
        "CurrentPage": "1",
        "SortBy": "CreatedOn",
        "SortDescending": true,
        "SearchTerms": "[SearchText]"
    }
}

Revised 09/27/2026