Skip to content

feat: add hover gesture support - #694

Open
adamhari wants to merge 25 commits into
FormidableLabs:mainfrom
adamhari:feat/hover-gesture
Open

adamhari wants to merge 25 commits into
FormidableLabs:mainfrom
adamhari:feat/hover-gesture

Conversation

@adamhari

@adamhari adamhari commented Oct 25, 2026 •

Copy link
Copy Markdown

Description

Adds hover support to victory-native using Gesture.Hover() from React Native Gesture Handler, exposed as a unified api across every chart — all cartesian chart types (line, area, bar, scatter, candlestick, … all render through CartesianChart) and pie/donut charts (PolarChart):

New props

  • enableHover?: boolean — builds the hover gesture. It is composed simultaneously with the existing press/transform gestures so it never competes with them, and touch-only behavior is unchanged. Hover activates on pointer devices (mouse/trackpad — e.g. web or desktop), so it defaults to true on web (with enableHover={false} to opt out) and stays opt-in elsewhere.
  • chartHoverState? — a Reanimated shared value the hover gesture writes into while the pointer is over the chart, consumed off the UI thread like chartPressState (no extra re-renders). Hover always has a state to drive, in this priority order:
    1. chartHoverState when provided — (Cartesian charts: a ChartPressState value from useChartPressState; Pie/donut charts: { index: SharedValue<number> } — the hovered slice index, or -1 over the donut hole, outside the pie, or off the chart). On PolarChart this prop is now optional: the chart maintains a built-in hover state that pie content reads with the new usePieHoverState() hook (exported from victory-native), so hover highlighting needs zero setup. Pass the prop only to consume the index outside the chart, where a provider-owned value can't be reached.
    2. chartPressState when chartHoverState is omitted — hover behaves exactly like press with no extra setup.
    3. A built-in hover state — Cartesian parity: with neither state passed, CartesianChart maintains a hover-only built-in state (mirroring PolarChart) and exposes it through the render functions' new hoverState field (isActive, x.value/x.position, y.<yKey>.value/position), so simple hover readouts need zero setup. It's undefined when you pass a state and read your own object instead.
  • chartHoverConfig?: ChartHoverConfig — { activeCursor?: string } cursor styling while hovering (web/desktop), and simultaneousWithExternalGesture to compose the hover gesture with custom gestures built outside the chart (mirrors chartPressConfig.pan.simultaneousWithExternalGesture).

TL;DR: Giving hover its own chartHoverState keeps hover and press interactions independent (each with its own isActive/values); omitting it makes hover and press act as one.

Example app

Hover examples are included, and a couple of bugs were fixed so the example app works properly on web:

  • enableHover wired into 18 example pages, plus a new /hover-press page demonstrating independent hover and press states.
  • Fixed a pre-existing web renderer freeze: under the React Compiler (reactCompiler: true), a chart-rendering wrapper that receives the Skia Font object as a prop triggers an infinite re-render. useFont is now hoisted inside each chart wrapper and the font props dropped.
  • example/metro.config.js pins the web resolver conditions to the library source (react-native) instead of freshly-built lib/dist, avoiding a TDZ crash caused by Metro workletizing the dist bundle on web.

Website docs

  • cartesian-chart.md / polar-chart.md: document enableHover, chartHoverState (including each chart's built-in hover state), and chartHoverConfig; cartesian render-function docs cover the new hoverState field.
  • chart-gestures.mdx: new "Hover gesture support" section, including distinct hover and press states.
  • pie-charts.md: cross-links the polar hover API.
  • Docusaurus build verified (incl. link checking).

Changeset

minor for victory-native.

Testing

  • lint / tsc --noEmit clean on lib, example, and website.
  • Full yarn test: 267 unit tests (including tests for the pie hover hit-test helper, the hover-config helper, and the new makeChartPressState built-in state factory) + 5/5 headless golden renders.
  • Verified live on web with real pointer events across the hover-enabled examples: hover activates on pointer enter, tracks values while moving, and deactivates on leave; pressing/clicking while hovering keeps a hover-driven state alive and hands control back to the hover on release; /hover-press shows hover and press states updating independently; pie/donut hover reports the hovered slice and stays idle over the donut hole and off-chart — all with zero props, via the built-in states. Console error-free throughout.

- CartesianChart: new optional \enableHover\ prop driving the first
  chartPressState via \Gesture.Hover()\ from react-native-gesture-handler;
  activates on pointer enter with live point tracking and deactivates on
  pointer leave/end/finalize.
- New optional \chartHoverConfig\ prop (\{ activeCursor?: string }\)
  to style the hover cursor.
- Composed with \Gesture.Simultaneous\ alongside existing pan/transform
  gestures so hover coexists with press-drag.
- Export \ChartHoverConfig\ type from the package entry point.
- Add \Gesture.Hover\ to the RNGH headless test stub so golden renders work.
- Add example screen (\/hover-gesture\) with cursor line + live readouts.
- Add example metro.config.js pinning web resolver conditions to the
  library source (avoids a TDZ crash from freshly-built lib/dist on web).
- Changeset (minor).
@changeset-bot

changeset-bot Bot commented Oct 25, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 6531333

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
victory-native Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@vercel

vercel Bot commented Oct 25, 2026

Copy link
Copy Markdown

@adamhari is attempting to deploy a commit to the Nearform Team on Vercel.

A member of the Team first needs to authorize it.

- PolarChart: new optional \enableHover\, \hoverState\ (\{ index }\
\: Reanimated
  shared value) and \chartHoverConfig\ props. A \Gesture.Hover()\ writes the
  chart-space pointer position (inverted through the active transform) into
  the polar chart context; \PieChart\ maps it onto slice geometry with a
  \useAnimatedReaction\ hit test (angle + radius/innerRadius) and writes the
  hovered slice index (-1 outside any slice / donut hole / off chart).
- Export \PieHoverState\ type from the package entry point.
- Examples: \enableHover\ + hover readouts wired into the bar chart and
  scatter examples (representative cartesian varieties) and slice hover
  readout in the donut chart example.
- Update changeset and route descriptions.
@adamhari adamhari changed the title feat: add hover gesture support (enableHover + chartHoverConfig) feat: add hover gesture support for all chart varieties (enableHover + chartHoverConfig + pie hoverState) Oct 25, 2026
- website: document \enableHover\ / \chartHoverConfig\ (CartesianChart),
  \enableHover\ / \hoverState\ / \chartHoverConfig\ (PolarChart), add a
  hover section with a full cartesian example to the Chart Gestures guide,
  and cross-link hover from the \chartPressState\ and Pie.Chart docs.
- examples: enable hover with slice readout in the pie chart example, and
  turn on \enableHover\ in candlestick, bar-with-tooltip and ordinal-data
  examples so their existing press tooltips respond to the mouse too.
Hover coverage for cartesian charts is now spread across the regular chart
examples (bar, bar-with-tooltip, scatter, ordinal-data, candlestick), so the
dedicated line-chart hover page is redundant. Update the website guide to
point at those examples instead.
A plain mouse click (press + release without movement) finalized the pan
gesture, whose end/finalize handlers unconditionally deactivated the first
chartPressState - resetting a tooltip that was driven by the (still active)
hover gesture. The press gesture's cleanup now consults \isPointerHovering\
(a shared value maintained by the hover gesture's active lifecycle) and
defers deactivation while the pointer keeps hovering; the hover gesture
deactivates the state when the pointer actually leaves the chart. Touch
behavior (hover never active) is unchanged, verified by the test suite.
The highlighted dot's radius was read from \state.x.position.value\
during render, but shared-value updates happen on the UI thread without a
re-render - so the dot lagged/desynced behind hover (and press) movement.
Compute the radius reactively with \useAnimatedReaction\ so it follows
both gestures accurately.
Same fix as ordinal-data: the highlighted dot's radius was read from the
press state shared value during render (and driven from render state via
useEffect), so it lagged/desynced behind hover and press movement since
shared-value updates happen on the UI thread without a re-render. Compute
the radius with useAnimatedReaction instead, and enable hover on the
example so the pointer tracks the line just like pressing.
@zibs

zibs commented Oct 27, 2026

Copy link
Copy Markdown
Collaborator

Love the idea of supporting hover more, might take me a few weeks to get around to this just fyi!

@adamhari adamhari changed the title feat: add hover gesture support for all chart varieties (enableHover + chartHoverConfig + pie hoverState) feat: add hover gesture support with a unified API (enableHover, hoverState, chartHoverConfig) Oct 31, 2026
@adamhari adamhari changed the title feat: add hover gesture support with a unified API (enableHover, hoverState, chartHoverConfig) feat: add hover gesture support with a unified API (enableHover, chartHoverState, chartHoverConfig) Oct 31, 2026
@adamhari
adamhari marked this pull request as ready for review November 2, 2026 18:22
@adamhari adamhari changed the title feat: add hover gesture support with a unified API (enableHover, chartHoverState, chartHoverConfig) feat: add hover gesture support Nov 3, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants