Stable Compatibility

This contract takes effect with TanStack Charts 1.0. Published 0.x releases continue to follow the Alpha policy.

Versions and deprecations#

The public Charts packages share one coordinated version. Patch releases fix defects. Minor releases add compatible capabilities. Removing a supported API, renaming an option, narrowing supported input, changing a documented default, or dropping a supported framework or runtime requires a major release.

A deprecated API remains supported throughout its current major version. Deprecations include a documented replacement and migration instructions. Production bundles do not need to retain migration warnings to provide this guarantee. A correctness fix may change an output that contradicted the documented behavior; its release notes explain the correction.

Public API#

The package export map and documented authoring and extension contracts define the supported surface. This includes custom marks, scales, interaction indexes, renderers, and the scene types those extensions are documented to consume or produce. Consumers can emit portable declarations for inferred chart definitions and marks from installed packages.

Source paths, private modules, undocumented DOM selectors, incidental scene nesting, generated keys, and exact serialized formatting are implementation details. Documented key identity, paint order, datum ownership, interaction, mount/update/destroy behavior, and SSR adoption are compatibility contracts.

New optional capabilities must preserve existing import boundaries. A consumer that does not import a capability must not gain its dependencies. Per-entry bundle gates and published measurements make this verifiable. Performance regressions are treated as defects and are investigated with equivalent builds and representative workloads.

Frameworks, runtimes, and renderers#

Supported peer ranges and runtime requirements are listed in Installation. A peer range does not promise identical features across renderers. The SVG, Canvas, and custom renderer contracts and their differences are documented in Rendering and Export.

Server-side scene compilation and SVG serialization do not require browser globals. DOM mounting requires the documented browser APIs. Optional motion, Canvas paths, image export, and framework hydration each retain their stated requirements. Unsupported capabilities must fail clearly rather than silently change their meaning.

Accessibility includes chart names and descriptions, documented keyboard interaction, focus restoration, and reduced-motion behavior. Applications own their surrounding controls, meaningful descriptions, and alternative data presentations. See Accessibility.

Experimental capabilities#

An experimental capability is identified in its reference documentation before release, with the supported scope and limitations. Its label is not permission to change unrelated stable APIs. Breaking changes to the experimental surface must include release notes and migration instructions.

React Native remains experimental until native-device validation proves the documented interaction, accessibility, and rendering behavior. Its current Metro, Expo, declaration, and component checks are described in Installation.

Unreleased proposals, draft PRs, and feature requests do not form part of this contract. A capability becomes supported when its implementation, public types, documentation, and release verification agree.