Working with Filters in Admiral

Ilya Zavilensky, backend developer

Jun 4, 2025

5 minutes

Contents

Types of Filters
How Admiral Sends Filters to the Backend

When building admin panels, it's often essential to provide efficient filtering for table data.

Filters are UI elements that allow users to quickly locate specific information based on defined criteria. Well-configured filters greatly simplify working with large data sets and improve the overall user experience.

You can see a visual demo of the filters in action here: https://admiral.dev.family/quick-filters.

Types of Filters

Admiral provides two convenient ways to filter data:

Quick filters — displayed directly above the table;
Advanced filters — accessible via a button.

Quick filters allow users to instantly apply the most commonly used filtering options without opening an additional menu. For more precise control, full-featured filters are available in a sidebar.

Standard Filters in Admiral

Standard filters let users manually refine table data based on specific fields. They can be accessed by clicking the “Filter” button in the top toolbar. This opens a sliding sidebar (drawer) that contains a filter form. This is the primary filtering method in Admiral, especially when dealing with a large number of parameters or more complex logic.

How Filters Work

Filters are configured in the filter section of the createCRUD function.

You simply pass a set of fields to the fields prop, and Admiral automatically renders the filter form. When values are changed and the filter is applied, the table refreshes automatically based on the selected criteria.

Example of setting up standard filters:


filter: {
    topToolbarButtonText: 'Filter',
    fields: (
        <>
            <TextInput
                name="search"
                label="Search"
                type="search"
                placeholder="Enter name or email"
            />
            <SelectInput
                name="group"
                label="Group"
                placeholder="Select a group"
                mode="multiple"
            >
                <SelectInput.Option value="admin">Administrators</SelectInput.Option>
                <SelectInput.Option value="project_manager">Project Managers</SelectInput.Option>
            </SelectInput>
            <SelectInput
                name="role"
                label="Role"
                placeholder="Select a role"
                allowClear
            >
                <SelectInput.Option value="accountant">Accountant</SelectInput.Option>
                <SelectInput.Option value="recruiter">Recruiter</SelectInput.Option>
            </SelectInput>
            <BooleanInput name="active" label="Active User" />
            <DatePickerInput
                name="registered_at"
                label="Registration Date"
                placeholder="Select a date"
                allowClear
            />
        </>
    ),
},

In this example, filters will be available by clicking the “Filter” button.
They will appear in a sidebar and allow users to filter data by name, email, groups, roles, activity status, and registration date.

Quick Filters in Admiral

quickFilters is a special key within the filter object that defines which filters should be displayed directly above the table, without opening the full filter panel.

It accepts an array of strings, each corresponding to the name of one of the previously defined filter fields.

Example:

filter: {
	quickFilters: ['search', 'group', 'role', 'active'],
}

In this example, the search, group, role, and active filters will be displayed as input fields directly above the table. Any additional filters (if defined) will remain accessible only via the “Filter” button.

This approach highlights the most frequently used filter parameters and makes the interface more convenient and user-friendly.

How Admiral Sends Filters to the Backend

Admiral constructs HTTP requests to the API that include both pagination parameters (page, perPage) and filtering criteria, all bundled under the filter object.

Example of a real request:

https://admiral.dev.family/api/users?page=1&perPage=10&filter[search]=User 10&filter[active]=true

Such a request is sent when we want to display all active users whose name contains “User 10”. In response, the backend should apply the filters and return an updated list of items to be displayed in the table.

Fetching Options

Some filter fields – such as SelectInput – require a list of options to function properly. To fetch these, Admiral sends a request to the backend at the {basePath}/filters endpoint. In response, the backend should return the appropriate list of options.

Using our example filters, the response might look like this:


{
  "options": {
	"group": [
  	{
    	"label": "Administration",
    	"value": "admin"
  	},
  	{
    	"label": "Project managers",
    	"value": "project_manager"
  	}
	],
	"role": [
  	{
    	"label": "Accountant",
    	"value": "accountant"
  	},
  	{
    	"label": "HR Officer",
    	"value": "recruiter"
  	}
	]
  }
}