The problem
Sitecore Search facet responses are flat arrays of { id, text, count }. That works for checkboxes, but not when content teams think in taxonomies (industry → sub-industry → detail) and users expect expand/collapse, breadcrumb chips and parent/child selection. Search does not return a nested facet tree.
The solution
Keep the hierarchy in the facet text as a path string, like Healthcare|Commercial|Property. Emit those strings into the index, filter with facet value IDs, and rebuild the tree in React by parsing the text.
The pipeline: tag meta → index fields → setSearchFacet → client-side tree.
Add a screenshot of the facet tree here.
Three delimiters, three jobs
| Delimiter | Where | Purpose |
|---|---|---|
| `\ | ` | Inside one value / facet.text
|
| `\ | \ | ` |
, |
URL query and filter.values
|
Multiple selected facet IDs |
The most common bug is putting Healthcare|Commercial in the URL instead of the facet value ID returned by Search.
Step 1: Tags in the index
For every hierarchical tag, emit each level you want facetable: Healthcare, Healthcare|Commercial, Healthcare|Commercial|Property. Siblings in the same meta attribute are joined with ||:
<meta
name="industryTags"
content="Healthcare||Healthcare|Commercial||Healthcare|Commercial|Property"
/>
The crawler's document extractor splits on || into index fields:
const splitMetaList = (content) =>
(content || "").split("||").map((s) => s.trim()).filter(Boolean);
const document = {
topic_tags: splitMetaList(meta.topicTags),
industry_tags: splitMetaList(meta.industryTags),
};
Each array element becomes a facetable value. Strings containing | stay whole; the UI splits them later.
Important: the facet field name in Search (and your CMS component's
facetid) must match the document property, for exampleindustry_tags, not the label "Industry".
Step 2: Sending filters to Sitecore Search
On every query, pass facet types. Add an or filter of IDs when the URL carries a selection:
function facetTypesFromUrl(
facets: { name: string }[],
searchParams: URLSearchParams,
) {
return facets.map((facet) => {
const ids = searchParams.get(facet.name)?.split(",").filter(Boolean) ?? [];
return ids.length
? { name: facet.name, filter: { type: "or", values: ids } }
: { name: facet.name };
});
}
request.setSearchFacet({
types: facetTypesFromUrl(
[{ name: "topic_tags" }, { name: "industry_tags" }],
searchParams,
),
});
A URL like /search?q=insurance&industry_tags=facetid_abc123,facetid_def456 becomes:
{
"facet": {
"types": [
{ "name": "topic_tags" },
{
"name": "industry_tags",
"filter": { "type": "or", "values": ["facetid_abc123", "facetid_def456"] }
}
]
}
}
setSearchFacet both applies the filters and returns updated buckets for the UI.
From click to API: a toggle in the facet UI runs cascade logic (parent plus descendants on select, careful ancestor cleanup on deselect), updates the URL with comma-separated IDs, fires onFacetClick / onFilterClick per ID so widget state matches, and the next request picks up the new filters. Only the id goes in the URL; text stays for display.
Step 3: Building the tree
Sort shallow paths first, map paths to nodes, then attach children:
const FACET_PATH_DELIMITER = "|";
type FacetValue = { id: string; text: string; count: number };
type FacetTreeNode = {
value: FacetValue;
label: string;
depth: number;
children: FacetTreeNode[];
};
function buildFacetTree(values: FacetValue[]): FacetTreeNode[] {
const sorted = [...values].sort(
(a, b) =>
a.text.split(FACET_PATH_DELIMITER).length -
b.text.split(FACET_PATH_DELIMITER).length,
);
const byPath = new Map<string, FacetTreeNode>();
const roots: FacetTreeNode[] = [];
for (const value of sorted) {
const parts = value.text.split(FACET_PATH_DELIMITER);
const node: FacetTreeNode = {
value,
label: parts[parts.length - 1]?.trim() ?? value.text,
depth: parts.length - 1,
children: [],
};
byPath.set(value.text, node);
const parent = byPath.get(parts.slice(0, -1).join(FACET_PATH_DELIMITER));
if (parts.length > 1 && parent) parent.children.push(node);
else roots.push(node); // no parent in the bucket: still show the node
}
return roots;
}
What the facet looks like
The API returns a flat list for industry_tags:
[
{ "id": "facetid_a1", "text": "Healthcare", "count": 42 },
{ "id": "facetid_a2", "text": "Healthcare|Commercial", "count": 18 },
{ "id": "facetid_a3", "text": "Healthcare|Commercial|Property", "count": 7 },
{ "id": "facetid_a4", "text": "Healthcare|Commercial|Casualty", "count": 5 },
{ "id": "facetid_a5", "text": "Healthcare|Public Sector", "count": 12 },
{ "id": "facetid_b1", "text": "Energy", "count": 30 }
]
The tree renders it with parents, two-level children and three-level children:
Industry
☐ ▾ Healthcare (42) ← parent (level 1)
☐ ▾ Commercial (18) ← child (level 2)
☐ Property (7) ← grandchild (level 3)
☐ Casualty (5) ← grandchild (level 3)
☐ ▸ Public Sector (12) ← child (level 2, collapsed)
☐ ▸ Energy (30) ← parent (level 1, collapsed)
Selecting Commercial cascades to its descendants and sends all three IDs:
▣ ▾ Healthcare (42) ← partial (ancestor, not in the URL)
☑ ▾ Commercial (18)
☑ Property (7)
☑ Casualty (5)
Active filters: [ Healthcare > Commercial × ]
URL: ?industry_tags=facetid_a2,facetid_a3,facetid_a4
UX details that matter:
- Checkbox label is the last segment only (
Commercial). - Active filter chips show breadcrumbs:
Healthcare > Commercial > Property. - The in-facet filter box prunes the tree but keeps branches with matches.
- A child appears checked when an ancestor ID is selected.
- Expand/collapse is local state, auto-expanding on search or when a descendant is selected.
Keep cascade and chip deduplication in small pure helpers so the facet component only renders.
Gotchas
-
Path strings in filters. If results come back empty, check that the URL and
filter.valueshold facet IDs, notParent|Childlabels. -
A
|inside a label breaks the tree. Escape it or change the delimiter. - Large taxonomies need facet pagination, often sorted by text ascending for cursor stability.
Why this approach
- Works with the stock widget:
setSearchFacet, facet IDs andorfilters are the documented contract. - Thin CMS, explicit index contract: hierarchy is just path strings on index fields.
- You own the UX: tree, in-facet search, cascade and chips are testable TypeScript.
- One tag-building module can feed both the crawler and API-pushed documents.
What I would improve next
Add your own ideas here, for example facet pagination, delimiter escaping, or unit tests for the cascade helpers.
Wrap up
Hierarchical facets in Sitecore Search are path-shaped strings in the index, ID-based filters in the request, and a tree algorithm in the browser. If you are building something similar, start by confirming that facet text looks like Parent|Child and that each path has a stable id. After that, the tree and cascade code is mostly mechanical.
I would love to hear how you handle taxonomies in your own Sitecore Search projects. Let me know in the comments.
Top comments (0)