Hierarchical Values

Enterprise

Introduction

A Hierarchical Values renders a List Filter’s value list as a collapsible hierarchy instead of a flat checkbox list. Values group under a path you derive — regions under their continent, dates under Year › Month › Day — and ticking a group node checks or unchecks every value beneath it. Leaf selection still drives the same in condition, so a tree list is purely a nicer view over the values a List Filter already offers.

It’s an option on the enterprise setFilter() helper:

import { setFilter } from '@zengrid/enterprise';

setFilter({
  field: 'region', header: 'Region',
  treeList: true,                                   // render as a tree
  treeListPathGetter: (v) =>                         // one segment per level
    String(v).includes('-') ? String(v).split('-') : [String(v)],
  treeListFormatter: ({ key, level, isLeaf }) =>     // label each node
    level === 0 && !isLeaf ? key + ' region' : key,
});

Turning on the tree

treeList: true swaps the flat list for the tree. On its own — with no path getter — every value sits at the top level (a one-deep tree), so the interesting part is the hierarchy you give it.

The mini search box and (Select all) row work exactly as they do for a flat List Filter: searching narrows the leaves and auto-opens the groups that hold a match, and select-all spans everything currently visible. A group’s own checkbox is tri-state — checked, unchecked, or a dash when its leaves are mixed.

Shaping the hierarchy

treeListPathGetter: (value) => string[] returns one segment per level, top level first. ZenGrid builds the branches from those paths and binds each value to a leaf at the end of its path:

// Dates → Year › Month › Day
treeListPathGetter: (v) => {
  const d = new Date(v);
  return [
    String(d.getFullYear()),
    d.toLocaleString('en-US', { month: 'long' }),
    String(d.getDate()),
  ];
},

Return a single-element array for a value that doesn’t nest (it becomes a top-level leaf), or an empty array to fall back to the value’s label. Order the tree with comparator: (a, b) => number over the raw values — for dates, compare timestamps so months read chronologically rather than alphabetically.

Labelling nodes

treeListFormatter: ({ key, level, parents, isLeaf, value }) => string sets each node’s label from its path segment without touching the value that gets filtered. level is the 0-based depth, parents are the ancestor segments, and isLeaf tells a group apart from a value. Use it to expand a code into a name at the top level while leaving leaves as-is.

Expanding

By default every level opens on show. treeListExpandDepth limits that — 0 starts fully collapsed, 1 opens the first level only — and the reader expands the rest with the twisties. Turn on showCount to append each node’s aggregated occurrence count.

Try it live

Open each column’s funnel to see the tree. Tick a group to select its whole branch, expand a node with its twisty, or search to auto-open matches. The buttons drive the same in filter from code.

Region by continentDates: Year › Month › DayCustom groups + collapsed

CodeDemoSplit

ResetRun ⌘⏎

Open the Region funnel: EU-* and US-* values fold under "Europe" and "Americas" (treeListFormatter renames the top level); APAC, LATAM and MEA stay top-level leaves. Tick a continent to select its whole branch.

Options reference

Option	What it does
treeList	Render the value list as a collapsible tree. Default false.
treeListPathGetter	(value) => string[] — the value’s path, top level first. Default: a single level per value.
treeListFormatter	({ key, level, parents, isLeaf, value }) => string — label each node. Default: the raw path segment.
treeListExpandDepth	Open groups down to this depth (0 = all collapsed). Default: every level.
comparator	Order the raw values: (a, b) => number. Drives the branch and leaf order.
showCount	Append each node’s aggregated occurrence count. Default false.

Every other List Filter and Value List option (values, valueFormatter, miniFilter, selectAll, defaultToNothingSelected) applies to a tree list too.

Next

• List Filter — the checkbox filter this tree is a view over, and how a selection maps to an in condition.
• Value List — supplying, sorting and formatting the values the tree groups.
• Filter Search — the search box that narrows the tree and auto-opens matches.