Lists and big lists
What it does
Sets when a list is paged on the server, how many rows a page shows, and how many columns an automatic list gets.
Default
Lists of up to 150 items load in the browser; bigger lists are paged on the server. 50 rows per page (also in the asset library), with 10, 20, 50, 100 and 200 to choose from. 5 columns to start with; admins and users can show as many as they like.
Options
| Key | Default | What it does |
|---|---|---|
list_limit | 1000 | Most objects held in the browser at once (1–20,000): a tree list with more is shown flat and paged on the server |
page_threshold | 150 | Lists with more objects than this are paged on the server (at most list_limit) |
relation_option_limit | 500 | Most choices in the dropdown for picking linked objects |
lists.page_sizes | [10, 20, 50, 100, 200] | Rows per page offered under a list (each 5–500, at most 10 choices) |
lists.page_size | 50 | Rows per page until a user picks another. Must be one of page_sizes. |
lists.asset_page_size | 50 | Items per page in the asset library. Must be one of page_sizes. |
lists.default_columns | 5 | Columns a list shows while nobody chose its columns, the name and built-in columns (Assigned to, Changed, Publication) included. At most max_columns when that is set; not set: 5, or max_columns when that is smaller |
lists.max_columns | 0 | Most field columns a list may show – in collections.<key>.columns, in Customize and in each user's Columns (0–100). 0 = no limit: everyone decides. The name, Assigned to, Changed and Publication are not counted |
Example
keel:
list_limit: 2000
lists:
page_sizes: [25, 50, 100]
page_size: 25
asset_page_size: 50
max_columns: 8
default_columns: 6
A page_size that is not in page_sizes stops cache:clear with: keel.lists.page_size: 20 is not one of page_sizes (25, 50, 100).
Small lists and big lists
- Small lists load in the browser. Lists with more than
page_thresholditems (orlist_limit, when that is lower) are paged, searched, filtered and sorted on the server, so lists of 50,000 items and more stay fast. No list is cut off. - A tree list loads whole up to
list_limititems. A bigger one is shown flat and paged on the server, with the note This list is too big to show as a tree: sub-items are listed with the others, page by page. - A linked-item field offers every item up to
relation_option_limit. With more items it offers the newest 20, and typing two or more letters searches all of them.
How users see it
- Each user's choice of rows per page is remembered with their user, for all lists. If
page_sizesno longer contains it, the list useslists.page_size. - For developers: the list API's
?size=must be one oflists.page_sizes; any other value giveslists.page_size.
See Lists for what editors see.
What admins change in Customize
The columns of each list (Customize → Columns): a checklist of every column the list can show – its fields, Assigned to, Changed and Publication – with the ticked ones in their order, as many as you like (or up to max_columns field columns when that is set). Page sizes and limits are only in keel.yaml.
Which columns a list shows:
- Chosen in Customize: as chosen.
collections.<key>.columnsin keel.yaml, or columns saved in Customize before Keel 2026-11: as configured, as before – the fields (at mostmax_columns), then Assigned to, Changed and Publication. They are not cut todefault_columns.- Nothing chosen:
default_columnscolumns in all – the name, the status field, Assigned to, then the list's fields in order, then Changed and Publication.
Upgrading: since 2026-11-06 there is no column limit unless max_columns is set (it was 5). A keel.yaml with max_columns keeps its meaning (field columns). Without default_columns it never asks for more columns than max_columns; only a default_columns bigger than max_columns stops cache:clear (keel.lists.default_columns: 6 is more than max_columns (4).).
Columns for each user
Above every list in Pimcore Studio, Columns lets each user show or hide columns for themselves (the name always stays; as many field columns as they like, or at most max_columns when that is set). The choice is remembered per user and list, in any browser; Reset to default goes back to the admin's choice, or to the automatic columns when none was made. Only the columns the list offers can be shown (not fields hidden in the class definition), and items the user may list but not open show only the list's usual columns. The cols request parameter of the list API (what the button sends) is limited to the columns the list offers, in the order asked, at most max_columns field columns when that is set; anything else is ignored. Hidden columns are not loaded, and sorting by a column that gets hidden goes back to the list's order. The search is the same for everyone whatever they show: it covers the list's usual columns and its own fields (including linked items' names), so counts, pages and Select all match. The classic admin dashboard has no Columns button; it shows the admin's columns.
Filters and saved views
Every list has the Filter button and saved views. There is nothing to set up and no keel.yaml
option. Filters read the class's query tables. A filter on a field without an index scans the class: on 75,000 objects a
page takes about 0.5 to 1.3 seconds. Keel's sort indexes also serve filters on the same columns.