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), pass layerIndex to bind the highlight to a single layer. 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({ aes: { y: 'sales' } }),
  geom.line({ aes: { y: 'trend' } }),
  // ...scales
  highlight(
    { variable: 'month', oneOf: ['Oct', 'Nov', 'Dec'] },
    { layerIndex: 0 }
  )
);

Omit layerIndex to evaluate the predicate against every layer.

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 a rendering concern, set once through config.appearance.highlightStyle:

config({ appearance: { highlightStyle: 'desaturate' } });

'dim' (the default) lowers the opacity of non-matched observations; 'desaturate' drains their color toward grey.

Mappings & aesthetics — the variables a predicate can name
Transforms — predicates run against post-transform columns
Appearance — the highlightStyle treatment

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