The problem
On a headless Sitecore site, the category chip on a "Latest Articles" card is usually just decoration. I wanted it to open article search with that category already selected. That sounds like one API call, but content hits and facet metadata come back in different shapes, so I had to bridge the two.
Here is the pattern I ended up with, using framework-neutral sample code you can adapt to any headless stack with a search or discovery API.
Labels on cards vs IDs in URLs
A discovery index stores article documents with fields authors understand: title, URL, publish date, image, and categories as human-readable text, usually a string array. Your search page, meanwhile, encodes filters in the URL with a query parameter name that matches the facet field, and a value that is the facet value ID, not the label shown on the page.
So an article hit looks like this:
{
"title": "Spring planting tips",
"url": "/articles/spring-planting-tips",
"category": ["Crop Protection"]
}
But the link you want on the chip is:
/articles/search?product_category=a1b2c3d4
Here a1b2c3d4 is opaque to editors and readers, and product_category is the facet field your search widget already understands. Neither representation is wrong: content hits are optimized for display, facet indexes for filtering. Your job is to join them at the edge where you render cards.
The solution
I use two Search calls and one UI join. The content call returns articles with category labels, the facet call returns label-to-ID pairs, and the UI combines them with the search page URL from the CMS. Each chip then links to search with that category pre-selected.
The deep link works because it uses the same facet field name and value ID the search widget produces when a user clicks a facet.
Shared types and flattening facets
Search facet payloads are usually nested. Flatten them once into a lookup table that maps a display label to a field name and a value ID.
type SearchArticle = {
id: string;
title: string;
url: string;
category?: string[]; // display labels from the index
};
type FacetValue = {
field: string; // becomes the query param name
id: string; // becomes the query param value
label: string; // matches the article's category text
};
type RawFacet = {
name: string;
value?: { id: string; text: string }[];
values?: { id: string; text: string }[];
};
function flattenFacets(raw: RawFacet[]): FacetValue[] {
return raw.flatMap((facet) => {
const values = facet.value ?? facet.values ?? [];
return values.map((v) => ({
field: facet.name,
id: v.id,
label: v.text,
}));
});
}
The value ?? values fallback is there because different search responses spell the array differently. Normalize it here so nothing downstream cares.
The two Search calls
Both calls hit the same search endpoint with the same widget, source and scope filters. Only the request body differs. Treat the code below as a sketch: field and parameter names vary by product, so adapt them to your search API.
Content call: latest articles
This handler asks Search for the newest N articles and maps hits to a stable JSON shape. Business filters (content type, locale, audience rules) live here because they decide which articles appear, not how category links are built.
// Framework-neutral handler: returns the latest N articles as plain JSON
async function getLatestArticles(limit = 3): Promise<SearchArticle[]> {
const body = {
widget: {
items: [{
widgetId: WIDGET_ID,
entity: 'content',
sources: [SOURCE_ID],
search: {
limit,
sort: { choices: true, value: [{ name: 'publish_date' }] },
filter: {
type: 'and',
filters: [
// e.g. only article templates, member rules, opt-outs
],
},
},
}],
},
context: { locale: { country: 'us', language: 'en' } },
};
const res = await fetch(SEARCH_URL, {
method: 'POST',
headers: { 'Content-Type': 'application/json', Authorization: SEARCH_KEY },
body: JSON.stringify(body),
});
if (!res.ok) throw new Error('Search request failed');
const data = await res.json();
const hits: Record<string, unknown>[] = data?.widgets?.[0]?.content ?? [];
return hits.map((hit) => ({
id: String(hit.id),
title: String(hit.name ?? hit.title ?? ''),
url: String(hit.url ?? ''),
category: (hit.product_category ?? []) as string[],
}));
}
The facet call is the same request with the same scope filters as your article search page, but with facet: { all: true } in place of the limit and sort. It returns fragments like { name: 'product_category', value: [{ id: 'a1b2c3', text: 'Crop Protection' }] }, which flattenFacets turns into { field: 'product_category', id: 'a1b2c3', label: 'Crop Protection' }. Wrap it in a getArticleFacets() function that mirrors the one above and returns data.widgets[0].facet.
Building the category URL
Editors control where search lives; developers control how placeholders become a query key and value. Keep the join in one pure function so it is trivial to test.
function buildCategorySearchUrl(
categoryLabel: string,
facetIndex: FacetValue[],
searchPageBaseUrl: string,
template = '{base}?{field}={id}'
): string | null {
if (!categoryLabel) return null;
const match = facetIndex.find((f) => f.label === categoryLabel);
if (!match) return null;
const base = searchPageBaseUrl.split('?')[0];
return template
.replace('{base}', base)
.replace('{field}', encodeURIComponent(match.field))
.replace('{id}', encodeURIComponent(match.id));
}
// Fall back to the unfiltered search page if the lookup fails
function categoryLink(
label: string,
facetIndex: FacetValue[],
searchPageUrl: string
): string {
return buildCategorySearchUrl(label, facetIndex, searchPageUrl) ?? searchPageUrl;
}
For example, base /articles/search and label "Crop Protection" produce /articles/search?product_category=a1b2c3.
If the lookup fails, link to the unfiltered search URL so the chip still navigates somewhere sensible. If your CMS stores the pattern as a field, pass it in as template so editors, not developers, own the URL shape.
Joining it in the UI
Load facets and articles (in parallel is fine), flatten the facets, then build each chip link from the first category label. The search page URL comes from the CMS, the same field that powers "View all articles".
const facetIndex = flattenFacets(await getArticleFacets());
const label = article.category?.[0] ?? '';
const searchUrl = categoryLink(label, facetIndex, searchPageUrl);
The only rule is that no link is built before the facet index exists.
Gotchas
Text matching is fragile. Joining on label === category[0] works while CMS labels and facet text stay in sync. Renames, reindex delays or duplicate labels break links quietly. Longer term, index a stable category ID on the document and match on that.
Only the first category gets a chip. Many documents carry several categories but the card shows one. Document that behavior, or add a "primary category" field in the CMS.
Keep the content API thin. Do not put buildCategorySearchUrl inside the latest-articles endpoint. Presentation joins belong next to the CMS fields they depend on (search page link, locale, editing mode), so a search page refactor never forces a backend redeploy.
Why this approach
- Links match the facet UI. The deep link uses the same field name and value ID the search widget produces, so the page recognizes it on load.
- Editors and developers each own their part. Editors control where search lives; developers control the URL template and facet join.
- Thin content API. URL logic stays out of the content proxy, so a search page refactor never forces a backend redeploy.
- Reusable. One cached facet lookup can serve Latest Articles, Related Articles and tag lists.
What I would improve next
Index a stable category ID on each article so the join no longer depends on matching label text, and add a "primary category" field in the CMS so the chip is deliberate when an article has several.
Wrap up
Two small API calls and one pure mapping function give you category links that editors can reason about and developers can maintain. If you build category links in your own Sitecore projects, I would love to hear how you handle it. Let me know in the comments.

Top comments (0)