Category pages

The category page widget takes over the product listing on your category pages: the grid, its filters and its sorting. Breadcrumbs, the heading, subcategory tiles and banners stay yours. It is the same listing as search results, served from a collection surface.

Its folder is integration/plp/.

Configuration

integration/plp/_config.ts:

export default {
  urlMatch: '^/c/',
  surface: 'lbs_collection_categories',
  lookup: { field: 'url' },
  params: {
    page: 'page',
    sort: { param: 'order', values: { 'price-asc': 'lbx:price:asc', 'price-desc': 'lbx:price:desc' } },
    facetParams: { brand: { param: 'brand' } },
  },
};

Key	Default
urlMatch	—	Required. A regular expression on the URL’s path, matching your category pages
surface	—	Required. A collection surface
lookup	—	How a page’s URL becomes a category — see below
params	—	Your own URL parameters, mapped onto the listing — see below
earlyHold	true	false when urlMatch also matches pages that are not category pages and style-host.css would hide something on them. The early-hold snippet matches on urlMatch alone.

Every listing key can be set here. Those left unset are taken from search/_config.ts: anchor, position, settleMs, reserveSelector, holdTimeoutMs, size, facets, facetSize, emptyValues, sorts, fields, baseFilters, rootClass, restoreOnBack, prefetchNextPage, facetsApply and facetGroups. So are templates and style-host.css, when plp/ has none of its own.

Sort labels come from the translations plp.sorts, and the built-in label for '' is “Recommended”.

From URL to category

Luma needs, for each page, a filter expression that selects the category’s products, and a title. Two ways to get them:

Look up the category record. lookup finds the catalog object of type category whose field equals the page’s path, without a trailing slash. absolute: true compares the origin and path instead; type names another object type. Then toFilter, set in plp/_widget.ts, turns that record into the filter:

integration/plp/_widget.ts

import type { PlpConfigType } from '@/types';

export default (c: PlpConfigType) => {
  c.toFilter = (category) => ({
    scope: { category_path: { eq: category.path } },
    title: category['@title'],
  });
};

Read it from the URL. fromUrl(url) returns the filter and title directly, with no lookup.

Either may return null: the page is left to your site. A category with no products is left to your site too.

Narrow urlMatch further with active(url) in plp/_init.ts.

Your URL parameters

A category page’s state lives in your own parameters, so your existing links, filters and canonical URLs keep working. params maps them:

Key
page	Your page parameter. Luma shows only the first page and appends the rest with “show more”, so your page 1 — or no page parameter — is Luma’s, and a later page is left to your own listing. Luma never writes it.
sort	{ "param", "values" }: your sort parameter and a map of your value to Luma’s field:direction
flags	On/off parameters with a fixed value: [{ "param": "stock", "value": "1", "filter": { … } }]. Labels come from plp.flags["stock=1"].
facetParams	Facet field → { "param", "values", "slug" }. values maps your values to catalog values; a value mapped to '' cannot be expressed, and its URL is left to your site. slug: false passes values through unchanged. With neither, your value is a slug of the catalog value.
separator	The separator between several values in one parameter
ranges	[{ "min", "max", "field" }]: two parameters read as a range filter on field
ignore	A regular expression of parameters that never stop a takeover, such as tracking parameters

A URL with a parameter Luma cannot express is left to your own listing, so no filter is silently dropped. A facet value your parameters cannot carry is written as lbx.<field>.

Facets per category

When the facets depend on the category — its own technical parameters, for example — set facetsFor(url, category) in plp/_widget.ts. It returns { facets, layout }: the fields to facet, in order, and optionally the sidebar’s group order including keys of your own. It may return a promise. null uses facets.

See also

• Search results — every listing key
• Collection — the request a category page sends