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 {
  createSpec,
  pipe,
  geom,
  scale,
  highlight,
} from '@graphysdk/viz-engine';
import { GraphProvider, GraphRenderer } from '@graphysdk/react-renderer';

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 a compile-time validation error, surfaced as a diagnostic rather than a silent no-op.

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

How the un-matched observations recede is stylesheet paint: entries scoped to the 'dimmed' state. The built-in stylesheet dims to alpha: 0.4; declare your own dimmed entry to change the look:

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

alpha lowers the opacity of non-matched observations; saturation: 0 drains their color toward grey.

Mappings & aesthetics — the variables a predicate can name
Transforms — predicates run against post-transform columns
Geoms — the stylesheet the dimmed entries live in

Get Started

Core concepts

Chart types

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

Predicates

Scope

Scoping to one layer

Combining highlights

Styling the de-emphasis

​Predicates

​Scope

​Scoping to one layer

​Combining highlights

​Styling the de-emphasis

​Related

Predicates

Scope

Scoping to one layer

Combining highlights

Styling the de-emphasis

Related