Value List

Enterprise

Introduction

The Value List is the checkbox list inside a List Filter: the set of distinct values the reader ticks to filter the column. By default setFilter() builds that list from the column’s own data, sorts it alphabetically, and labels each value with String(value). This page is about taking control of the list — what values it holds, how they’re ordered, and how they read.

setFilter() is an enterprise column helper, so these are all options on it:

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

setFilter({
  field: 'region', header: 'Region',
  values: ['APAC', 'EU-West', 'US-East'],   // what's in the list
  comparator: (a, b) => /* … */ 0,          // the order
  valueFormatter: (v) => String(v),         // the labels
});

Supplying the values

values decides what the list holds. It takes three forms:

Form	Signature	Use it for
Array	values: unknown[]	A fixed, hand-authored list — including values that aren’t in the data (they show with a count of 0).
Synchronous	values: (derived) => list	Filter, reorder or extend the values ZenGrid derived from the column.
Asynchronous	values: (derived, success) => void	Fetch the list elsewhere (a lookup table, an API) and hand it back via success(list). The popup shows a Loading… state until it fires.

Omit values entirely and the list is every distinct value in the column. Supplied values are decoupled from the data, so the list stays stable even when a value currently has no matching rows — useful for canonical lookups (all regions, every status) where you don’t want the options to come and go with the data.

// Async: load the option list from a server, then hand it back.
setFilter({
  field: 'role', header: 'Role',
  defaultToNothingSelected: true,
  values: (derived, success) => {
    fetchRoles().then(success); // popup shows "Loading…" until this resolves
  },
});

defaultToNothingSelected starts the list with nothing ticked — the grid shows no rows until the reader picks a value — instead of the default “everything ticked / no filter.”

Sorting the list

comparator: (a, b) => number orders the raw values (not the labels). The default is a locale-aware ascending sort by label; supply a comparator to force a domain order (severity, workflow stage) or to reverse it.

const ORDER = ['Active', 'Trial', 'Churned'];
setFilter({
  field: 'status', header: 'Status',
  comparator: (a, b) => ORDER.indexOf(a) - ORDER.indexOf(b),
});

Formatting & missing values

valueFormatter: (value) => string sets each row’s label without changing the value that gets filtered — map codes to names, upper-case, add units. Blank values (null, undefined, '') collapse to a single (Blanks) row. Turn on showCount to append each value’s occurrence count.

Try it live

Open the Region, Role or Status funnel in each variant to see how the list was shaped. In the async variant, watch the Loading… state before the options appear. The buttons drive the same in filter from code.

Supplying the valuesAsync values + nothing selectedSorting & formatting

CodeDemoSplit

ResetRun ⌘⏎

Region’s list is a hand-authored array, not the derived uniques. Open the funnel: "ANZ" is present even though no row has it, so with showCount it reads 0 — the list is decoupled from the data.

Options reference

Option	What it does
values	Source the list: an array, a synchronous (derived) => list, or an asynchronous (derived, success) => void.
comparator	Order the raw values: (a, b) => number. Default is ascending by label.
valueFormatter	Label each value: (value) => string. Blanks show as (Blanks).
showCount	Append each value’s occurrence count. Default false.
defaultToNothingSelected	Start with nothing ticked (grid shows no rows until a value is picked). Default false.

Next

• List Filter — the checkbox filter these list options belong to, and how a selection maps to an in condition.
• Filter Search — the search box that narrows the list.
• Column Filters — the in operator the Set Filter builds on.