Highlights

A highlight emphasizes the observations that match a predicate by dimming the ones that don’t. You describe what to match, not which pixels to paint, so the highlight follows the data through re-sorts, filters and updates.

import { useMemo } from 'react';
import {
  GraphProvider,
  GraphRenderer,
  createSpec,
  pipe,
  geom,
  scale,
  highlight,
} from '@graphysdk/react';

const data = {
  columns: [{ key: 'quarter' }, { key: 'region' }, { key: 'sales' }],
  rows: [
    { quarter: 'Q1', region: 'EU', sales: 1200 },
    { quarter: 'Q1', region: 'US', sales: 1500 },
    { quarter: 'Q2', region: 'EU', sales: 1800 },
    { quarter: 'Q2', region: 'US', sales: 1600 },
    { quarter: 'Q3', region: 'EU', sales: 2400 },
    { quarter: 'Q3', region: 'US', sales: 2200 },
    { quarter: 'Q4', region: 'EU', sales: 2800 },
    { quarter: 'Q4', region: 'US', sales: 3100 },
  ],
};

export function RegionalSales() {
  const spec = useMemo(
    () =>
      pipe(
        createSpec({ x: 'quarter', y: 'sales', color: 'region' }),
        geom.bar({ position: 'dodge' }),
        scale.x(),
        scale.y(),
        scale.color.discrete(),
        highlight({ variable: 'region', eq: 'EU' }) // EU bars stay vivid, the rest fade
      ),
    []
  );

  return (
    <GraphProvider spec={spec} data={data}>
      <GraphRenderer />
    </GraphProvider>
  );
}

Predicates

The first argument to highlight() is a predicate: a test against your post-transform columns. A field predicate names a variable and a comparison:

Predicate	Matches
`{ variable: 'region', eq: 'EU' }`	exact value
`{ variable: 'quarter', oneOf: ['Q3', 'Q4'] }`	any of a set
`{ variable: 'sales', gt: 2000 }`	`gt` / `gte` / `lt` / `lte` — ordered comparison
`{ variable: 'sales', range: [1500, 2500] }`	inclusive numeric range

Ordered operators (gt, gte, lt, lte, range) need a numeric or date column. Using one on a text column is an INVALID_PREDICATE_OPERATOR warning that drops the whole highlight; the chart still renders without it. Naming a column the data doesn’t have (UNKNOWN_VARIABLE) does the same, and one bad leaf inside an and or or drops the highlight it belongs to. Both arrive as diagnostics.

There is no neq here; write { not: { variable: 'region', eq: 'EU' } } instead. The neq operator on transform.filter belongs to a separate comparison vocabulary. Combine predicates with and, or and not:

highlight({
  and: [
    { variable: 'region', eq: 'EU' },
    { variable: 'quarter', oneOf: ['Q3', 'Q4'] },
  ],
}); // EU, but only in the second half

Scope

By default a highlight matches single observations. The scope option widens each match to a larger unit:

Scope	Effect
`'data-point'` (default)	Only the rows that satisfy the predicate; the rest of their group stays dimmed
`'series'`	Any matching row expands to its whole group — highlight an entire line, area, or set of bars
`'x-value'`	Any matching row expands to every observation sharing its x — highlight a vertical slice across groups

highlight({ variable: 'region', eq: 'EU' }, { scope: 'series' });

Scoping to one layer

In a multi-layer chart (bars plus a trend line, say), bind the highlight to one layer: give the layer an id and name it with layerId. Observations in other layers are never tested, so a Q4 highlight on the bars leaves the trend line alone:

pipe(
  createSpec({ x: 'month' }),
  geom.bar({ id: 'bars', aes: { y: 'sales' } }),
  geom.line({ aes: { y: 'trend' } }),
  // ...scales
  highlight(
    { variable: 'month', oneOf: ['Oct', 'Nov', 'Dec'] },
    { layerId: 'bars' }
  )
);

Omit layerId to test the predicate against every layer. A layer you never name gets an id at resolve time, so scoping is the one case where naming it yourself matters.

Combining highlights

Multiple highlight() calls accumulate, and the engine unions their matches: an observation matched by any highlight is emphasized. Two separate highlights behave like an or:

pipe(
  // ...
  highlight({ variable: 'sales', gte: 2000 }),
  highlight({ variable: 'region', eq: 'US' }) // rows ≥ 2000 OR any US row
);

The union is exactly an or, so this equals a single highlight with an or predicate: the same observations match and the result is the same:

pipe(
  // ...
  highlight({
    or: [
      { variable: 'sales', gte: 2000 },
      { variable: 'region', eq: 'US' },
    ],
  })
);

Use one or predicate when the two conditions are one idea. Use two highlights when they are independent and you may toggle them separately.

Styling the de-emphasis

Every non-matched observation carries the dimmed style state, and one stylesheet entry decides what that state looks like. The built-in stylesheet dims to alpha: 0.4. Put your own entry in overrides, where it decides the cascade:

styles({
  overrides: [style.geom({ saturation: 0, alpha: 0.6 }, { state: 'dimmed' })],
});

alpha lowers the opacity of non-matched observations; saturation: 0 drains their color to gray. SetHighlightDimStyleCommand makes the same choice as a command, for a picker in an editing UI. It writes exactly that entry:

import {
  SetHighlightDimStyleCommand,
  readHighlightDimStyle,
} from '@graphysdk/viz-engine';

dispatch(new SetHighlightDimStyleCommand({ dimStyle: 'desaturate' })); // 'dim' | 'desaturate'

'dim' writes the built-in alpha: 0.4 out in full; 'desaturate' writes { saturation: 0, alpha: 0.6 }. readHighlightDimStyle(spec) reads the current choice back, to select the right item in the picker.

Highlight commands

highlight() has a one-for-one command mirror:

Command	Params
`AddHighlightCommand`	`predicate`, `id?`, `scope?`, `layerId?`, `index?`
`RemoveHighlightCommand`	`id`

The id is settled when the command is constructed, so RemoveHighlightCommand can address a highlight that was added without one.

Styling — the stylesheet the dimmed entries live in, and the where condition that takes this same predicate language
Mappings & aesthetics — the variables a predicate can name
Transforms — predicates run against post-transform columns

Get Started

Core concepts

Chart types

Themes

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

Predicates

Scope

Scoping to one layer

Combining highlights

Styling the de-emphasis

Highlight commands

​Predicates

​Scope

​Scoping to one layer

​Combining highlights

​Styling the de-emphasis

​Highlight commands

​Related

Predicates

Scope

Scoping to one layer

Combining highlights

Styling the de-emphasis

Highlight commands

Related