Highlights

A highlight emphasises the observations that match a predicate by de-emphasising the ones that don’t. You describe what to match — not which pixels to paint — so the highlight tracks 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.palette(),
        highlight({ variable: 'region', eq: 'EU' }) // EU bars stay vivid, the rest fade
      ),
    []
  );

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

Predicates

The first argument to highlight() is a predicate — a test against your post-transform columns. Field predicates name 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 against a categorical field is an INVALID_PREDICATE_OPERATOR warning that drops the whole highlight — the chart still renders, minus that emphasis. Naming a column the data doesn’t have (UNKNOWN_VARIABLE) behaves the same way, 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 the logical forms 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 individual observations. The scope option expands each match to a larger visual unit:

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

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

Scoping to one layer

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

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 evaluate the predicate against every layer. A layer you never name gets an id assigned 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 emphasised. So two separate highlights behave like an or:

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

Because the union is exactly an or, this is equivalent to a single highlight with an or predicate — same matched observations, same result:

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

Reach for the single or predicate when the two conditions are one idea; reach for two separate highlights when they’re independent emphases you might toggle separately.

Styling the de-emphasis

Every non-matched observation carries the dimmed style state, and what that state looks like is one stylesheet entry. The built-in stylesheet dims to alpha: 0.4; put your own entry in overrides, where it wins 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 toward grey. SetHighlightDimStyleCommand is the same choice as one 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 wash (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 imperative 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

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