# TanStack Ranger: the slider logic separated from the slider markup

> Ranger is a headless library for range and multi-range sliders, published for React, Preact, Solid, Vue, Svelte and Angular. You get the behaviour, the state and the keyboard handling, and you write the markup yourself, which is a smaller commitment than adopting a component library and a larger one than writing a slider from scratch.

**TanStack/ranger** — 🤖 Headless utilities for building range and multi-range sliders in React, Preact, Solid, Vue, Svelte and Angular

- Repository: https://github.com/TanStack/ranger
- Website: https://tanstack.com/ranger
- Stars: 841 · Forks: 81
- Language: TypeScript
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/tanstack-ranger

## Headless means you write the element, the library writes the behaviour

Ranger is described as headless UI for building a ranger component in TypeScript and JavaScript, and the repository description calls it headless utilities for building range and multi-range sliders in React, Preact, Solid, Vue, Svelte and Angular.

The headless contract is the whole idea. You get the logic, the state and the interaction handling. You get no markup, no styling and no default look. A ranger is a slider that can have one handle or two, and the hard part of a slider is rarely the visual, it is the pointer maths, the keyboard interaction, the ARIA roles and attributes, and the state that has to stay consistent when the value is a range rather than a number.

That split is why the framework list is so long. A headless library has almost no rendering surface of its own, so the same behaviour core can be bound to six different view libraries, and each binding is thin. Compare that with a component library, where every additional framework means porting the visual layer as well.

The project sits in the TanStack family alongside React Query, TanStack Table and React Charts, and the README points at the whole TanStack collection. The documentation lives at tanstack.com/ranger, which the README calls the place for docs, guides and API.

The audience is a frontend developer who wants accessible slider behaviour and is not willing to hand over their design system to a component library. If you are looking for a styled slider to drop in, this is the wrong package, and the wrong question to ask of it.

## Five capabilities, and the multi-range case is the interesting one

The README lists a short feature set, and reading it closely tells you what the library actually models.

Single or multiple handles covers both a plain slider and a range slider with two ends. Handle divider items is the feature that distinguishes a range slider from two separate sliders, since the region between the two handles can itself be a target, and a range control often needs to support dragging the middle section as a unit rather than moving one end at a time.

Custom steps or step-size means the value can be quantised, whether to whole numbers, to a percentage, or to whatever grid the data actually lives on. Custom ticks means you can render your own marks and labels underneath the track, which is usually where the design requirements live.

And then there is the headless principle itself as the first item on the list.

That list is short, and for a slider library it is honest. There is no mention of a value display, a tooltip, a label, an orientation other than the obvious, a vertical layout, or touch-specific behaviour. Some of those may exist in the API documentation, and some may be things the headless design leaves to you.

The multi-range case is where the value proposition is strongest, because a two-handle slider with correct keyboard behaviour and correct ARIA markup is a genuinely fiddly component, and one that a design system rarely gets right. A library that handles the interaction and lets you handle the pixels is a reasonable split of that work.

## The npm package is @tanstack/ranger, with a separate React binding

The package published to npm is @tanstack/ranger, and the README links to its npm page and to a bundle size report for the latest version, which is the badge a headless library should be advertising rather than a feature count.

The release history shows the split. The most recent tags are @tanstack/react-ranger at 0.0.5 and @tanstack/ranger at 0.0.4, both published on the same day, 2025-12-06, with an earlier v0.0.6 tag from 2024-01-02. So the framework-specific binding and the core package are versioned and released together, and they are both pre-1.0.

That last point is the one to hold onto when you plan the dependency. At 0.0.x, the version number carries no compatibility promise in the usual sense, and the fact that the core and the React binding are separate packages means you have two coordinates to keep aligned rather than one.

The repository itself is a pnpm workspace with an Nx build, a packages/ directory and an examples/ directory that currently holds a single React example. The root package manifest is private and the workspace is driven by pnpm with the packageManager field pinning the pnpm version.

The last push to the repository was on 2026-08-03, and the project is MIT licensed with a LICENSE file at the root. The README carries a semantic-release badge and a GitHub Discussions link, so the project is run with changesets and the standard release tooling rather than hand-edited version numbers.

## What the repository scripts say about how the project is checked

The root package manifest is mostly a quality gate, and reading it tells you what the maintainers consider non-negotiable.

```json
  "scripts": {
    "test": "pnpm run test:ci",
    "test:pr": "nx affected --targets=test:sherif,test:knip,test:docs,test:lib,test:types,build",
    "test:ci": "nx run-many --targets=test:sherif,test:knip,test:docs,test:lib,test:types,build",
    "test:knip": "knip",
    "test:sherif": "sherif",
    "test:docs": "node scripts/verify-links.ts",
  },
```

The ci target runs six distinct checks in one command, the type and library tests being the obvious two. The remaining ones are worth knowing about because they each catch a specific kind of mistake.

knip finds unused files, dependencies and exports, which matters more in a library than in an application, since an exported symbol nobody imports is API surface you have to keep supporting. sherif is a linter for monorepo package configuration, checking that the workspace packages agree with each other about dependencies, versions and publishing settings. The docs check runs a script that verifies links, so a broken link in the documentation fails the build rather than waiting for a reader to find it.

The docs test is a nice touch for a library whose entire value is developer experience, and the exclusions of the examples directory from the type and library tests are the usual compromise, since the example apps are built separately.

The rest of the manifest is ordinary modern monorepo tooling: Nx for the task graph, changesets for versioning and publishing, prettier for formatting, vitest for the test runner, publint for validating what actually gets published, and the arethetypeswrong core package for checking that the shipped type definitions match the module format they claim.

## A headless library still leaves you the accessibility work you cannot skip

It is worth being clear about what headless does not do for you.

A headless slider gives you the state and the interaction. It does not give you the ARIA attributes unless it wires them for you, and it does not give you the visual focus ring, the touch target size, the contrast of the filled track against the empty one, or the way the handle looks when it is at its minimum. Those are still your job.

The trade-off is real and it cuts both ways. With a component library you get a slider that is accessible out of the box, and you get it in a style that may not match the other twenty components in your design system, and you spend your time overriding it. With a headless library you get the behaviour and the freedom, and you spend your time on the markup, and the accessibility attributes are only as good as the implementation you write.

The documentation site is the place to find out which side of that line Ranger lands on. The README itself does not enumerate the API, does not show a single code example, and does not describe the ARIA strategy. That is a documentation gap rather than a design flaw, and it is worth accounting for before you commit to it.

The same goes for the framework coverage. The description claims React, Preact, Solid, Vue, Svelte and Angular, and the repository has a single React example. The other bindings may be complete, and the release tags show the React one being published, but the example directory as it stands tells you that React is where the demonstrated usage lives.

## Where TanStack Ranger is the wrong tool

The first wrong-tool case is a project that needs a finished component today. If the requirement is a slider that looks like the other sliders in your product, and building the visual layer is not part of the interesting problem, a headless library asks you to solve a problem you did not have. The marketing-style pitch of drop in and go does not apply here, because there is nothing to drop in.

The second case is a project that needs features the list does not mention. Vertical sliders, touch-specific gestures, a value display with formatting, a label component, an editable numeric input alongside the track, an RTL layout: some of these may be in the API and some may not, but the README's feature list is short enough that you should check the documentation before assuming.

The third case is a team that needs a stable API. The core package is at 0.0.4 and the React binding at 0.0.5, both from December 2025, and the repository's last push was on 2026-08-03. A 0.0.x library with a small surface is cheap to adopt and cheap to replace, but it is also cheap for its author to reshape, and you should expect to absorb breaking changes on a minor version bump rather than a major one.

There is also the multi-framework question to think about. Ranger's pitch is that one behaviour core serves six view libraries, and that is a genuine advantage if you have a mixed codebase. If you only ship React, the cross-framework support is a nice-to-have you are not using, and you should weigh the library against writing the interaction logic yourself for your own design system.

On licensing, the project is MIT with a LICENSE file at the root, so there is no copyleft consideration and no obligation on how you build on it. The cost of adoption is entirely engineering time.

## Conclusion

Ranger suits a team that wants accessible slider behaviour without adopting a component library, because the headless approach keeps the markup, the styling and the design system entirely in your hands while the fiddly parts of the interaction live in the library. It does not suit a project that wants a finished slider component on the page today, and it does not suit a codebase that has no appetite for writing the visual layer. Before adopting, read the API documentation at tanstack.com/ranger, check the published package for your framework among the six listed, and pin the @tanstack/ranger and @tanstack/react-ranger versions together, since the two are released in step.

## FAQ

### What is TanStack Ranger used for?

Ranger provides headless utilities for building range and multi-range sliders in React, Preact, Solid, Vue, Svelte and Angular. It handles the behaviour and state while you write the markup and styling yourself.

### Which features does TanStack Ranger support?

The README lists headless design, single or multiple handles, handle divider items, custom steps or step size, and custom ticks. Documentation, guides and the API reference are at tanstack.com/ranger.

### Which npm packages does TanStack Ranger publish?

The core package is @tanstack/ranger, published on npm, with a separate framework binding such as @tanstack/react-ranger. The two are versioned and released together, and both were at 0.0.x in December 2025.

### How is the TanStack Ranger repository checked in CI?

The test command runs six targets through Nx: type tests, library tests, knip for unused files and exports, sherif for monorepo package consistency, a documentation link check, and the build. Examples are excluded from the type and library test targets.

### What license is TanStack Ranger released under?

TanStack Ranger is MIT licensed, with the LICENSE file at the root of the repository. The project uses changesets for versioning and publishing, and semantic-release is referenced in the README badges.

## Sources

- [License: MIT](https://github.com/TanStack/ranger/blob/main/LICENSE)
- [Project website](https://tanstack.com/ranger)
- [README](https://github.com/TanStack/ranger/blob/main/README.md)
- [Releases](https://github.com/TanStack/ranger/releases)
- [TanStack/ranger on GitHub](https://github.com/TanStack/ranger)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tanstack-ranger