Content Manager URL & Filter State#

Overview#

The Content Manager's ListView encodes all view state — filters, pagination, sort, locale, and other plugin parameters — in the URL query string. This makes individual views deep-linkable and bookmarkable. State flows from user interaction → URL update → API request in a unidirectional pattern mediated by useQueryParams and a qs-based serialization layer.

URL Shape#

The query string uses the qs library for serialization/deserialization, enabling deeply nested objects (e.g., filters[$and][0][status][$eq]=draft). The top-level keys recognised by the ListView are typed as ListViewQuery:

Core Hook: useQueryParams#

useQueryParams (packages/core/admin/admin/src/hooks/useQueryParams.ts) is the shared foundation:

• Reads the current location.search, stripping any leading ?, and merges it with optional initialParams via qs.parse 1.
• Writes via setQuery(nextParams, method, replace):
  • method='push' (default) merges nextParams into the current query.
  • method='remove' deletes the specified keys.
  • Calls navigate({ search: stringify(nextQuery, { encode: false }) }, { replace }) 2.
• Returns [{ query, rawQuery }, setQuery].

The ListView calls it with defaults for page, pageSize, and sort 3.

Persistent State: usePersistentPartialQueryParams#

usePersistentPartialQueryParams (packages/core/content-manager/admin/src/hooks/usePersistentQueryParams.ts) layers localStorage persistence on top of useQueryParams:

• Accepts a PersistentQueryConfig — a map of storage keys to { paths, scoped? }. Keys scoped to a model are namespaced KEY:modelUID 4.
• On mount, reads matching keys from localStorage, deep-merges with URL params (URL wins), and navigates to the merged state. Sets isHydrated=true after this 5.
• On query change, serializes only the configured paths back to localStorage 6.
• Returns { isHydrated }. The ListView delays the API fetch until isHydrated is true to avoid a flash of un-restored state 7.

The ListView configures two persistent entries 8:

STRAPI_LIST_VIEW_SETTINGS:<model> → paths: ['sort', 'filters', 'pageSize'], scoped: true
STRAPI_LOCALE → paths: ['plugins.i18n.locale'], scoped: false

Filter State Flow#

Filter Serialization (Popover → URL)#

Filters.Popover.handleSubmit 9 builds the filter entry:

• Values are encodeURIComponent-encoded (filter-free operators like $null get "true" instead).
• Relations are nested: { [field]: { [mainField|id]: { [op]: value } } }.
• The new entry is appended (or replaces when editing) in query.filters.$and, then pushed to the URL via setQuery({ filters: newFilterQuery, page: 1 }, 'push', true) 10.

Filter Deserialization (URL → display)#

Filters.List 11 reads query.filters.$and and renders an AttributeTag for each entry. Values are decoded with decodeURIComponent before display 12. Clicking a tag removes it from $and and resets page to 1.

Schema-Aware Filter Options#

The ListView wraps Filters with a custom listViewFilters.Root that:

1. Derives a displayedFilters array from the content type schema and layout.
2. Adds id, documentId, and (for D&P content types) a special __status filter 13.
3. Runs the INJECT_LIST_VIEW_FILTERS hook waterfall so plugins can add filters 14.
4. Passes the resolved filter options into the base Filters.Root as options.

Status Sort Interaction#

When a __status filter is active, the status column sort is disabled. If sort=status:* is already in the URL when a status filter is applied, an effect in ListViewPage strips it from the query 15.

URL → API Request: buildValidParams#

Before calling the API, the raw query is passed through buildValidParams (packages/core/content-manager/admin/src/utils/api.ts):

• Removes the plugins key.
• Promotes each plugin's values to the root level (e.g., plugins.i18n.locale=en → locale=en).
• The resulting flat object is sent as API query params to useGetAllDocumentsQuery 16.

Edge Cases & Known Fixes#

• Trailing ? in URLs: When qs.stringify({}) returns "", the paramsSerializer in getFetchClient.ts was previously emitting ?, which broke publish deduplication guards. Fixed by skipping the ? when the serialized result is empty 17.
• Hydration guard: API calls are skipped while isHydrated=false to prevent the page loading before localStorage state is restored 7.
• Over-range pagination: If the API returns a pagination.page beyond pagination.pageCount, the page is reset to pageCount via a navigate({ replace: true }) 18.
• Plugin params propagation: When navigating to create/edit entries, only query.plugins is forwarded (not sort/filters), preserving locale without carrying filter state into the edit view 19.

Key Files#