TanStack React Charts 1.5.0: Was ist neu und wie Sie upgraden

TanStack React Charts 1.5.0 ist auf npm: optionale Tooltip-Verzögerungen, ein Scene-Subscription-Fix und ein Dependency-Bump im React-Adapter. So upgraden Sie.

Huifer
Huifer
9. November 202610 min read
Auch verfügbar auf:English · 中文

Geschrieben von Huifer, Solo-Entwickler und Maintainer von TanStack Ship. Ich habe das Tarball-Archiv @tanstack/react-charts@1.5.0 aus der npm-Registry gezogen, die mitgelieferten Typdefinitionen gelesen und das Paket in einem Scratch-Projekt mit React 19 installiert, um zu bestätigen, dass die Subpath-Exports auflösen. Das 1.5.0-Changelog ist kurz: optionale Tooltip-Show-/Hide-Delays und ein Scene-Subscription-Fix. Meine Hauptfrage war, ob die neuen Delay-Optionen das Standardverhalten ändern; Changelog und Typdeklarationen sagen, dass ihr Standardwert 0 ist. Für dieses Release habe ich kein Produktions-Upgrade auf einem Live-Dashboard durchgeführt, daher ist alles zur realen Render-Kostenlage [needs source].

Offenlegung: Huifer ist der Autor von TanStack Ship und erhält Vergütung aus TanStack-Ship-Verkäufen. Dieser Beitrag ist ein unabhängiger technischer Leitfaden zum Release. Er ist nicht von TanStack gesponsert, und kein TanStack-Maintainer hat ihn geprüft.

Verifizierte Quellen: TanStack Charts overview · Tooltips and Focus guide · Stable Compatibility contract · npm registry 1.5.0 · TanStack/charts repository · web.dev · Cloudflare developers · Zuletzt aktualisiert: 9. November 2026 · Changelog


TanStack React Charts 1.5.0: Was ist neu und wie Sie upgraden

Direkte Antwort: @tanstack/react-charts 1.5.0 ist ein Minor-Release, das am 7. November 2026 auf npm veröffentlicht wurde. Es ergänzt die optionalen Optionen showDelay und hideDelay für den integrierten HTML-Tooltip und behebt einen Scene-Subscription-Bug. Das React-Adapter-Paket selbst hat keine neue API-Oberfläche: Es re-exportiert dieselbe Chart-Komponente und erhält das neue Tooltip-Verhalten über seine @tanstack/charts@1.5.0-Dependency. Wenn Sie auf 1.4.0 oder früher sind, ist das Upgrade ein reiner Versions-Bump ohne erforderliche Code-Änderungen, weil die Delay-Optionen Opt-in sind und standardmäßig 0 sind.

TL;DR

  • Was sich geändert hat: @tanstack/charts 1.5.0 ergänzt die optionalen Optionen tooltip.showDelay und tooltip.hideDelay (Millisekunden, Standard 0) mit Abbruch bei Zielverlust, Wiedereintritt, Options-Updates und Zerstörung des Hosts.
  • Auswirkung auf React: @tanstack/react-charts 1.5.0 ist ein Dependency-Bump-Release; die Chart-API ist unverändert.
  • Upgrade: Version anheben, den React-Peer-Bereich (^18 || ^19) bestätigen und einen Build plus einen Tooltip-Smoke-Test ausführen.
  • Kompatibilität: der stabile 1.x-Vertrag gilt weiter; Patch- und Minor-Releases dürfen öffentliche APIs nicht entfernen oder umbenennen.
  • Nicht verifiziert: Ich habe weder das Tooltip-Timing zur Laufzeit im Browser noch die Bundle-Size-Differenz gemessen; beides bleibt [needs source].

Definition (KI-zitierfähig): @tanstack/react-charts 1.5.0 ist der React-Adapter für TanStack Charts, eine framework-agnostische Charting-Bibliothek. Der Adapter rendert Chart-Definitionen als SVG oder Canvas und stellt seit 1.5.0 Opt-in-Show- und Hide-Delays für den HTML-Tooltip über das @tanstack/charts-Core-Paket bereit.

Was 1.5.0 tatsächlich ändert

Das Changelog, wörtlich gelesen

Das CHANGELOG.md des Repositorys listet für 1.5.0 zwei Änderungen unter @tanstack/charts und einen Dependency-Bump unter @tanstack/react-charts:

  1. Minor-Änderung, PR #262: optionale Show- und Hide-Delays für den integrierten HTML-Tooltip, mit Abbruch bei Zielverlust, Wiedereintritt, Options-Updates und Zerstörung. Das Changelog hält fest, dass die Immediate-Defaults und die geerbte Motion erhalten bleiben.
  2. Patch-Änderung, PR #235: Presentation-Subscriber und Animation-Completion bleiben auf der neuesten Scene, wenn ein Subscriber eine andere Scene rendert.
  3. @tanstack/react-charts 1.5.0: „Updated dependencies“ — das React-Adapter-Paket selbst hat keine gelistete API-Änderung.

Das ist das gesamte Release. Es gibt kein neues Mark, keinen neuen Scale, keinen neuen Renderer und keine umbenannte Option im React-Adapter.

Was die Registry bestätigt

Ich habe das 1.5.0-Manifest aus der npm-Registry gelesen. Die folgenden Werte stammen gemessen von registry.npmjs.org/@tanstack/react-charts/1.5.0:

FeldWertWarum das für ein Upgrade zählt
version1.5.0Das Release, auf das Sie wechseln.
licenseMITUnverändert.
typemoduleNur ESM; kein CommonJS-Einstieg.
sideEffectsfalseTree-shakeable; keine globalen Side Effects zu berücksichtigen.
peerDependenciesreact und react-dom ^18.0.0 || ^19.0.0React 18 und 19 werden beide unterstützt.
dependencies@tanstack/charts: 1.5.0Der Adapter delegiert an das Core-Paket in derselben Version.
exports., ./core, ./canvas, ./tooltipVier Subpaths; kein Default-CJS-Export.
unpackedSize25.213 BytesDas veröffentlichte Tarball ist entpackt rund 25 KB groß.
fileCount17Entspricht dem installierten Layout, das ich geprüft habe.

Das Manifest verzeichnet außerdem eine SLSA-Provenance-Attestation und eine GitHub-Actions-Trusted-Publisher-OIDC-Identität — ein Hinweis darauf, dass das Tarball in der CI des Projekts gebaut und nicht von einem Laptop aus veröffentlicht wurde. Das ist ein Supply-Chain-Signal, kein funktionales.

Was die Registry nicht bestätigt

Die Registry sagt Ihnen, was veröffentlicht wurde, nicht was sich semantisch geändert hat:

  • Verhaltens-Defaults. Sie kann nicht sagen, dass showDelay und hideDelay standardmäßig 0 sind; das tun die Typdeklarationen und die Doku.
  • Breaking Changes. Sie kann nicht sagen, ob eine öffentliche API entfernt wurde; das tun der Kompatibilitätsvertrag und das Changelog.
  • Laufzeitkosten. Sie kann nicht sagen, ob die neuen Timer die Bundle-Size oder das Render-Timing ändern. Das habe ich nicht gemessen; behandeln Sie jede Zahl als [needs source].

Die neue Tooltip-Delay-API

Semantik von showDelay und hideDelay

Die 1.5.0-Funktion ist im Tooltips and Focus guide dokumentiert. Beide Optionen werden im Tooltip-Optionsobjekt gesetzt und in Millisekunden angegeben:

ts
import { defineChart } from '@tanstack/charts'
import { tooltip } from '@tanstack/charts/tooltip'

const interactiveChart = defineChart(chartDefinition, {
  tooltip: {
    use: tooltip,
    showDelay: 150,
    hideDelay: 100,
  },
})

Das Beispiel im Guide nutzt showDelay: 150 und hideDelay: 100, damit kurze Hover keine Tooltips öffnen und Zeit bleibt zurückzukehren, bevor sich der Tooltip versteckt. Beide sind standardmäßig 0 — deshalb beschreibt das Changelog die Defaults als „immediate“ und deshalb sollte ein Upgrade ohne Code-Änderungen identisch aussehen.

Abbruch, Wiedereintritt und Timer-Lebenszyklus

Die Delay-Implementierung hat einen spezifischen Lebenszyklus, den Sie lesen sollten, bevor Sie sich darauf verlassen:

  • Verliert der Fokus vor der Show-Deadline, wird die ausstehende Anzeige abgebrochen.
  • Wechselt der Pointer zwischen Zielen, bleibt die Show-Deadline erhalten, und es erscheint das neueste Ziel.
  • Kehrt der Pointer während des Hide-Delays zurück, wird das Verstecken abgebrochen.
  • Ändert sich ein ausstehendes Delay, startet seine Uhr neu; ein unverändertes Delay bleibt erhalten.
  • Wird der Host zerstört, werden beide Timer sofort abgebrochen.
  • Nichtpositive und nichtfinite Delays wirken wie 0; positive Werte werden auf 2.147.483.647 Millisekunden begrenzt, um einen nativen Timer-Overflow zu vermeiden.

Diese Regeln sind für Dashboards relevant, in denen sich der Pointer schnell über viele Punkte bewegt. Eine naive Timer-Implementierung würde Tooltips stapeln oder einen veralteten Tooltip offen lassen; die dokumentierten Abbruchregeln sind der Grund, warum Sie ein Delay setzen können, ohne genau diesen Bug einzuführen.

Zusammenspiel mit Motion und Reduced Motion

Die Delay-Optionen sind unabhängig von der Animation. Die Doku stellt fest, dass motion: false die Animation deaktiviert, während die autorisierten Visibility-Delays weiter gelten, und dass die Delay-Optionen zum integrierten HTML-Tooltip gehören, nicht zum React-Native-Tooltip. Ein Motion-Renderer liefert weiterhin die Entry-, Movement-, Retargeting- und Exit-Transitions des Tooltips; das Delay verschiebt lediglich den Beginn des Erscheinens oder Versteckens. Die Reduced-Motion-Policy des Adapters gilt weiterhin. Für Dashboard-Accessibility siehe die Accessibility-Richtlinien von web.dev und die Doku für Cloudflare-Entwickler.

Upgrade-Pfad für React-Projekte

Schritt 1: pinnen und installieren

bash
# Wenn Sie das React-Adapter-Paket direkt installieren
npm install @tanstack/react-charts@1.5.0

# Wenn Sie der Single-Package-Empfehlung der Doku folgen
npm install @tanstack/charts@1.5.0 react react-dom

Die Installationsseite der Doku empfiehlt, @tanstack/charts zu installieren und die Framework-Peers zu ergänzen, weil die Framework-Adapter auf Subpaths dieses Pakets liegen (@tanstack/charts/react, @tanstack/charts/react-native und so weiter). Das separate Paket @tanstack/react-charts ist der React-spezifische Einstiegspunkt und hängt von @tanstack/charts in derselben Version ab. Ich habe in einem Scratch-Projekt verifiziert, dass beide Wege auflösen.

Schritt 2: den React-Peer-Bereich und die RSC-Grenzen prüfen

Das 1.5.0-Manifest deklariert react und react-dom mit ^18.0.0 || ^19.0.0. React 17 ist eine harte Grenze; React 18 und 19 erfüllen den Bereich.

Für React Server Components besagt das 1.1.0-Changelog, dass die React-Chart-Einträge als Client-Komponenten markiert sind. Das habe ich im veröffentlichten Paket bestätigt: Jede JavaScript-Datei unter @tanstack/react-charts/dist/ trägt eine "use client"-Direktive. Der SSR and hydration guide ergänzt, dass der Server keinen Container messen kann; liefern Sie daher width/height, width/aspectRatio, initialWidth/height oder initialWidth/aspectRatio. Wenn CSS die Höhe kontrolliert und Sie keine angeben, nutzt die Server-Ausgabe einen 320-Fallback:

tsx
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}
    />
  )
}

Schritt 3: die Subpath-Exports verifizieren

Der Adapter stellt vier Subpaths bereit. Ich habe geprüft, worauf jeder einzelne zur Laufzeit aufgelöst hat:

SubpathExportsVerwenden, wenn
@tanstack/react-chartsChartStandard-SVG/DOM-Host.
@tanstack/react-charts/coreChart (ein RendererChart-Alias)Sie bringen Ihren eigenen Renderer mit.
@tanstack/react-charts/canvasChart (ein CanvasChart-Alias)Sie wollen den Canvas-Renderer.
@tanstack/react-charts/tooltipChart, RendererChart, CanvasChartSie wollen den HTML-Tooltip-Host mit renderTooltipBody.

Der ./tooltip-Subpath ist derjenige, der ein renderTooltipBody-Prop akzeptiert und die Chart in einen portal-basierten Tooltip-Host einhüllt. Wenn Sie bereits ./tooltip importieren, sind die 1.5.0-Delay-Optionen über dasselbe Tooltip-Optionsobjekt verfügbar.

Ihre Charts nach dem Upgrade verifizieren

Ein Build-Zeit-Check

bash
# Installierte Version und Core-Dependency bestätigen
npm ls @tanstack/react-charts @tanstack/charts

# Bestätigen, dass die Subpaths unter Ihrem Bundler auflösen
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))))"

Ich habe das in einem Scratch-Projekt mit React 19 ausgeführt, und alle vier Subpaths haben aufgelöst. Die Ausgabe listete Chart für den Root-, Core- und Canvas-Subpath sowie Chart, RendererChart und CanvasChart für den Tooltip-Subpath.

Ein Laufzeit-Smoke-Test

Die Delay-Optionen sind die einzige verhaltensbezogene Ergänzung; ein Smoke-Test sollte sie daher abdecken:

  1. Auf einen Punkt hovern und sich vor der Show-Deadline entfernen; bestätigen, dass kein Tooltip erscheint.
  2. Die Show-Deadline abwarten, zu einem zweiten Punkt bewegen und bestätigen, dass der Tooltip ohne Flackern neu zielt.
  3. Während des Hide-Delays weggehen und zurückkehren; bestätigen, dass sich der Tooltip nicht versteckt.
  4. Unmounten, während ein Delay aussteht; bestätigen, dass kein Timer weiterläuft.

Diese Sequenz habe ich nicht im Browser ausgeführt und kann daher kein Bestehen oder Scheitern melden; behandeln Sie sie als Checkliste, nicht als Ergebnis. Für eine Baseline vor dem Upgrade behandelt der MRR-Metrics-Dashboard-Beitrag die Chart-Formen, die ein Revenue-Dashboard typischerweise braucht.

Was ich verifiziert habe und was nicht

BehauptungBeweistypStatus
1.5.0 am 7. November 2026 veröffentlichtgemessen (npm-Registry)bestätigt
React-Peer-Bereich ^18 || ^19gemessen (Registry-Manifest)bestätigt
Vier Adapter-Subpaths lösen aufgemessen (Scratch-Installation, React 19)bestätigt
"use client" in allen dist-Dateiengemessen (grep im installierten Paket)bestätigt
showDelay/hideDelay standardmäßig 0user-provided (Doku + Changelog)laut Doku bestätigt
Tooltip-Timing-Verhalten im Browsernicht gemessen[needs source]
Bundle-Size-Differenz gegenüber 1.4.0nicht gemessen[needs source]
React-18-Verhaltennicht gemessen (ich nutzte React 19)[needs source]

Welche Template-Fähigkeit das unterstützt

Dieser Teil zählt, wenn Sie ein SaaS-Template auswählen statt eine bestehende App zu upgraden. Die Käuferentscheidung ist einfach: Hält der Dashboard-Charting-Stack des Templates mit der Bibliothek Schritt, von der er abhängt, und ist die Chart-Schicht hydration-safe?

Ein Template, das @tanstack/react-charts auf einer alten Version pinnt oder Charts ohne serverseitige Size-Policy rendert, erzeugt Layout Shift und Hydration-Warnungen beim ersten Paint. Der 1.x-Vertrag bedeutet, dass ein Minor-Bump wie 1.5.0 Ihre Charts nicht brechen sollte; die Upgrade-Kosten sind also niedrig — aber nur, wenn der Chart-Wrapper des Templates undokumentierte Internals vermeidet.

Um nach dieser Achse zu vergleichen, sehen Sie nach, welche SaaS-Templates eine Dashboard-Chart-Schicht enthalten, und stöbern Sie in den TanStack-Templates, um zu prüfen, welche Starter überhaupt eine mitliefern.

FAQ

Ist 1.5.0 ein Breaking Change?

Nein. Der 1.x-Kompatibilitätsvertrag verlangt ein Major-Release, um eine unterstützte API zu entfernen, eine Option umzubenennen oder einen dokumentierten Default zu ändern. Das 1.5.0-Changelog listet ein Minor-Feature und einen Patch-Fix, und die einzige Änderung des React-Adapters ist ein Dependency-Bump. Wenn Ihr Build bricht, ist die wahrscheinliche Ursache ein undokumentiertes Internal, keine Änderung an einer öffentlichen API.

Muss ich meine Chart-Definitionen ändern?

Nein. Die Delay-Optionen sind Opt-in und standardmäßig 0, daher rendert eine bestehende Definition exakt wie zuvor. Code müssen Sie nur ändern, wenn Sie das neue Verhalten wollen: Ergänzen Sie showDelay und hideDelay im Tooltip-Optionsobjekt. Definitionen, Marks, Scales und Renderer bleiben unverändert.

Gilt das Delay für React Native?

Nein. Die Doku stellt fest, dass die Delay-Optionen zum integrierten HTML-Tooltip gehören, nicht zum React-Native-Tooltip. React-Native-Support ist in der 1.x-Linie weiterhin experimentell; behandeln Sie die Native-Oberfläche als eigenen Kompatibilitätsstrang. Wenn Sie sowohl ein Web-Dashboard als auch eine Native-App ausliefern, verifizieren Sie jeden Adapter unabhängig.

Was, wenn ich eine exakte Version pinne?

Pinnen bleibt der richtige Standard für die Produktion. Die Registry zeigt, dass 1.5.0 am 7. November 2026 veröffentlicht wurde, und das Paket nutzt eine feste Release-Gruppe über Frameworks hinweg; das Pinnen von @tanstack/react-charts auf 1.5.0 pinnt also auch @tanstack/charts auf 1.5.0. Wenn Sie auf 1.4.0 bleiben, behalten Sie das alte Tooltip-Verhalten und verpassen den Scene-Subscription-Fix.

Fazit

Das 1.5.0-Release ist klein und sicher: zwei Änderungen im Core-Paket, ein Dependency-Bump im React-Adapter und ein Kompatibilitätsvertrag, der seit 1.0 stabil ist. Das Upgrade ist ein Versions-Bump, und das einzige neue Verhalten sind Opt-in-Tooltip-Delays, die standardmäßig 0 sind. Ich habe das Manifest, die Subpath-Auflösung und die Client-Component-Direktiven verifiziert; Browser-Timing und Bundle-Size habe ich nicht gemessen — behandeln Sie beides als [needs source].

Nächster Schritt: Sehen Sie sich ein TanStack-Template an und führen Sie den vierstufigen Tooltip-Smoke-Test mit Ihren eigenen Daten aus. Für Lizenz- und Pricing-Fragen: Template-Pricing ansehen.

Mehr zu diesem Thema

Dieser Beitrag beleuchtet einen Aspekt. Beginne mit dem vollständigen Leitfaden oder sieh dir die anderen Aspekte an.