Skip to main content
Keel Docs Showcase

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

KeyDefaultWhat it does
list_limit1000Most objects held in the browser at once (1–20,000): a tree list with more is shown flat and paged on the server
page_threshold150Lists with more objects than this are paged on the server (at most list_limit)
relation_option_limit500Most 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_size50Rows per page until a user picks another. Must be one of page_sizes.
lists.asset_page_size50Items per page in the asset library. Must be one of page_sizes.
lists.default_columns5Columns 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_columns0Most 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

yaml
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_threshold items (or list_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_limit items. 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_sizes no longer contains it, the list uses lists.page_size.
  • For developers: the list API's ?size= must be one of lists.page_sizes; any other value gives lists.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>.columns in keel.yaml, or columns saved in Customize before Keel 2026-11: as configured, as before – the fields (at most max_columns), then Assigned to, Changed and Publication. They are not cut to default_columns.
  • Nothing chosen: default_columns columns 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.