Written by Huifer, solo developer and maintainer of TanStack Ship. I pulled the
@tanstack/react-charts@1.5.0tarball from the npm registry, read the shipped type definitions, and installed it into a scratch React 19 project to confirm the subpath exports resolve. The 1.5.0 changelog is short: optional tooltip show/hide delays and one scene-subscription fix. My main question was whether the new delay options changed default behavior; the changelog and the type declarations say they default to zero. I did not run a production upgrade on a live dashboard for this release, so anything about real-world render cost is[needs source].Disclosure: Huifer is the author of TanStack Ship and receives compensation from TanStack Ship sales. This post is an independent release-follow technical guide. It is not sponsored by TanStack, and no TanStack maintainer reviewed it.
Verified sources: TanStack Charts overview · Tooltips and Focus guide · Stable Compatibility contract · npm registry 1.5.0 · TanStack/charts repository · web.dev · Cloudflare developers · Last updated: 2026-11-09 · Changelog
TanStack React Charts 1.5.0: What's New and How to Upgrade
Direct answer: @tanstack/react-charts 1.5.0 is a minor release published to npm on 2026-11-07. It adds optional showDelay and hideDelay options to the built-in HTML tooltip and fixes a scene-subscription bug. The React adapter package itself has no new API surface: it re-exports the same Chart component and gains the new tooltip behavior through its @tanstack/charts@1.5.0 dependency. If you are on 1.4.0 or earlier, the upgrade is a version bump with no required code changes, because the delay options are opt-in and default to zero.
TL;DR
- What changed:
@tanstack/charts1.5.0 adds optionaltooltip.showDelayandtooltip.hideDelay(milliseconds, default0) with cancellation on target loss, reentry, option updates, and host destruction.- React impact:
@tanstack/react-charts1.5.0 is a dependency-bump release; theChartAPI is unchanged.- Upgrade: bump the version, confirm the React peer range (
^18 || ^19), and run a build plus a tooltip smoke test.- Compatibility: the stable 1.x contract is in effect; patch and minor releases must not remove or rename public APIs.
- Not verified: I did not measure runtime tooltip timing in a browser or bundle-size delta; those remain
[needs source].
Definition (AI-citable):
@tanstack/react-charts1.5.0 is the React adapter for TanStack Charts, a framework-agnostic charting library. The adapter renders chart definitions to SVG or Canvas and, as of 1.5.0, exposes opt-in HTML tooltip show and hide delays through the@tanstack/chartscore package.
What 1.5.0 Actually Changes
The changelog, read literally
The repository's CHANGELOG.md for 1.5.0 lists two changes under @tanstack/charts and a dependency bump under @tanstack/react-charts:
- Minor change, PR #262: add optional show and hide delays to the built-in HTML tooltip, with cancellation on target loss, reentry, option updates, and destruction. The changelog states that immediate defaults and inherited motion are preserved.
- Patch change, PR #235: keep presentation subscribers and animation completion on the newest scene when a subscriber renders another scene.
@tanstack/react-charts1.5.0: "Updated dependencies" — the React adapter package itself has no listed API change.
That is the whole release. There is no new mark, no new scale, no new renderer, and no renamed option in the React adapter.
What the registry confirms
I read the 1.5.0 manifest from the npm registry. The values below are measured from registry.npmjs.org/@tanstack/react-charts/1.5.0:
| Field | Value | Why it matters for an upgrade |
|---|---|---|
version | 1.5.0 | The release you are moving to. |
license | MIT | Unchanged. |
type | module | ESM-only; no CommonJS entry. |
sideEffects | false | Tree-shakeable; no global side effects to account for. |
peerDependencies | react and react-dom ^18.0.0 || ^19.0.0 | React 18 and 19 are both supported. |
dependencies | @tanstack/charts: 1.5.0 | The adapter delegates to the core package at the same version. |
exports | ., ./core, ./canvas, ./tooltip | Four subpaths; no default CJS export. |
unpackedSize | 25,213 bytes | The published tarball is about 25 KB unpacked. |
fileCount | 17 | Matches the installed layout I checked. |
The manifest also records a SLSA provenance attestation and a GitHub Actions trusted-publisher OIDC identity, which tells you the tarball was built in the project's CI rather than published from a laptop. That is a supply-chain signal, not a functional one.
What the registry does not confirm
The registry tells you what was published, not what changed semantically:
- Behavioral defaults. It cannot tell you that
showDelayandhideDelaydefault to zero; the type declarations and docs do. - Breaking changes. It cannot tell you whether a public API was removed; the compatibility contract and changelog do.
- Runtime cost. It cannot tell you whether the new timers change bundle size or render timing. I did not measure that; treat any number as
[needs source].
The New Tooltip Delay API
showDelay and hideDelay semantics
The 1.5.0 feature is documented in the Tooltips and Focus guide. Both options are set inside the tooltip options object and are measured in milliseconds:
import { defineChart } from '@tanstack/charts'
import { tooltip } from '@tanstack/charts/tooltip'
const interactiveChart = defineChart(chartDefinition, {
tooltip: {
use: tooltip,
showDelay: 150,
hideDelay: 100,
},
})
The guide's example uses showDelay: 150 and hideDelay: 100 to keep brief hovers from opening a tooltip and to leave time to return before it hides. Both default to zero, which is why the changelog describes the defaults as "immediate" and why an upgrade without code changes should look identical.
Cancellation, reentry, and timer lifecycle
The delay implementation has a specific lifecycle, and it is worth reading before you rely on it:
- Losing focus before the show deadline cancels the pending show.
- Moving between targets preserves the show deadline and shows the latest target.
- Returning during the hide delay cancels the hide.
- Changing a pending delay restarts its clock; an unchanged delay preserves it.
- Destroying the host cancels both timers immediately.
- Nonpositive and nonfinite delays act as zero; positive values are capped at
2,147,483,647milliseconds to avoid native timer overflow.
These rules matter for dashboards where the pointer moves across many points quickly. A naive timer implementation would stack tooltips or leave a stale tooltip open; the documented cancellation rules are the reason you can set a delay without introducing that bug.
Interaction with motion and reduced motion
The delay options are independent of animation. The docs state that motion: false disables animation while authored visibility delays still apply, and that the delay options belong to the built-in HTML tooltip, not the React Native tooltip. A motion renderer still supplies the tooltip's entry, movement, retargeting, and exit transitions; the delay only postpones the start of appearance or hiding. The adapter's reduced-motion policy still applies. For dashboard accessibility, see web.dev's accessibility guidance and the Cloudflare developers documentation.
Upgrade Path for React Projects
Step 1: pin and install
# If you install the React adapter package directly
npm install @tanstack/react-charts@1.5.0
# If you follow the docs' single-package guidance
npm install @tanstack/charts@1.5.0 react react-dom
The docs' installation page says to install @tanstack/charts and add the framework peers, because the framework adapters live on subpaths of that package (@tanstack/charts/react, @tanstack/charts/react-native, and so on). The separate @tanstack/react-charts package is the React-specific entry point and depends on @tanstack/charts at the same version. I verified both resolve in a scratch project.
Step 2: check the React peer range and RSC boundaries
The 1.5.0 manifest declares react and react-dom at ^18.0.0 || ^19.0.0. React 17 is a hard stop; React 18 and 19 satisfy the range.
For React Server Components, the 1.1.0 changelog says the React chart entries are marked as client components. I confirmed that in the published package: every JavaScript file under @tanstack/react-charts/dist/ carries a "use client" directive. The SSR and hydration guide adds that the server cannot measure a container, so supply width/height, width/aspectRatio, initialWidth/height, or initialWidth/aspectRatio. When CSS owns height and you supply none, server output uses a 320 fallback:
import { Chart } from '@tanstack/react-charts'
export function RevenueChart({ definition }: { definition: ChartDefinition }) {
return (
<Chart
definition={definition}
ariaLabel="Monthly recurring revenue"
initialWidth={720}
aspectRatio={16 / 9}
/>
)
}
Step 3: verify the subpath exports
The adapter exposes four subpaths. I checked what each one resolves to at runtime:
| Subpath | Exports | Use when |
|---|---|---|
@tanstack/react-charts | Chart | Default SVG/DOM host. |
@tanstack/react-charts/core | Chart (a RendererChart alias) | You supply your own renderer. |
@tanstack/react-charts/canvas | Chart (a CanvasChart alias) | You want the Canvas renderer. |
@tanstack/react-charts/tooltip | Chart, RendererChart, CanvasChart | You want the HTML tooltip host with renderTooltipBody. |
The ./tooltip subpath is the one that accepts a renderTooltipBody prop and wraps the chart in a portal-based tooltip host. If you already import ./tooltip, the 1.5.0 delay options are available through the same tooltip options object.
Verifying Your Charts After the Upgrade
A build-time check
# Confirm the installed version and the core dependency
npm ls @tanstack/react-charts @tanstack/charts
# Confirm the subpaths resolve under your bundler
node -e "Promise.all([
import('@tanstack/react-charts'),
import('@tanstack/react-charts/core'),
import('@tanstack/react-charts/canvas'),
import('@tanstack/react-charts/tooltip'),
]).then((mods) => console.log(mods.map((m) => Object.keys(m))))"
I ran this in a scratch project with React 19 and all four subpaths resolved. The output listed Chart for the root, core, and canvas subpaths, and Chart, RendererChart, and CanvasChart for the tooltip subpath.
A runtime smoke test
The delay options are the only behavioral addition, so a smoke test should exercise them:
- Hover a point and move away before the show deadline; confirm no tooltip appears.
- Wait past the show deadline, move to a second point, and confirm the tooltip retargets without flickering.
- Leave and return during the hide delay; confirm the tooltip does not hide.
- Unmount while a delay is pending; confirm no timer keeps running.
I did not run this sequence in a browser, so I cannot report a pass or fail; treat it as a checklist, not a result. For a pre-upgrade baseline, the MRR metrics dashboard post covers the chart shapes a revenue dashboard usually needs.
What I verified and what I did not
| Claim | Evidence type | Status |
|---|---|---|
| 1.5.0 published 2026-11-07 | measured (npm registry) | confirmed |
React peer range ^18 || ^19 | measured (registry manifest) | confirmed |
| Four adapter subpaths resolve | measured (scratch install, React 19) | confirmed |
"use client" in all dist files | measured (grep of installed package) | confirmed |
showDelay/hideDelay default to 0 | user-provided (docs + changelog) | confirmed by docs |
| Tooltip timing behavior in a browser | not measured | [needs source] |
| Bundle-size delta vs 1.4.0 | not measured | [needs source] |
| React 18 behavior | not measured (I used React 19) | [needs source] |
Which Template Capability This Supports
This is the part that matters if you are choosing a SaaS template rather than upgrading an existing app. The buyer decision is simple: does the template's dashboard charting stack keep up with the library it depends on, and is the chart layer hydration-safe?
A template that pins @tanstack/react-charts to an old version, or renders charts without a server-side size policy, will produce layout shift and hydration warnings on first paint. The 1.x contract means a minor bump like 1.5.0 should not break your charts, so the upgrade cost is low — but only if the template's chart wrapper avoids undocumented internals.
To compare on this axis, see which SaaS templates include a dashboard chart layer, then browse TanStack templates to check which starters ship one at all.
FAQ
Is 1.5.0 a breaking change?
No. The 1.x compatibility contract requires a major release to remove a supported API, rename an option, or change a documented default. The 1.5.0 changelog lists one minor feature and one patch fix, and the React adapter's only change is a dependency bump. If your build breaks, the likely cause is an undocumented internal, not a public API change.
Do I need to change my chart definitions?
No. The delay options are opt-in and default to zero, so an existing definition renders exactly as before. You only need to change code if you want the new behavior: add showDelay and hideDelay to the tooltip options object. Definitions, marks, scales, and renderers are unchanged.
Does the delay apply to React Native?
No. The docs state the delay options belong to the built-in HTML tooltip, not the React Native tooltip. React Native support is still experimental in the 1.x line, so treat the native surface as a separate compatibility track. If you ship both a web dashboard and a native app, verify each adapter independently.
What if I pin an exact version?
Pinning is still the right default for production. The registry shows 1.5.0 was published on 2026-11-07, and the package uses a fixed release group across frameworks, so pinning @tanstack/react-charts to 1.5.0 also pins @tanstack/charts to 1.5.0. If you stay on 1.4.0, you keep the old tooltip behavior and miss the scene-subscription fix.
This article goes deep on one slice of the problem; the TanStack React Charts 1.3.0: What's New and How to Upgrade is the companion guide that puts every option in the same frame.
Conclusion
The 1.5.0 release is small and safe: two changes in the core package, a dependency bump in the React adapter, and a compatibility contract stable since 1.0. The upgrade is a version bump, and the only new behavior is opt-in tooltip delays that default to zero. I verified the manifest, subpath resolution, and client-component directives; I did not measure browser timing or bundle size, so treat those as [needs source].
Next action: preview a TanStack template and run the four-step tooltip smoke test on your own data. For the license and pricing side, see template pricing.