Tanstack Ranger

作者 tanstack-skills6f5521ecbdfb无许可证35 个星标收录于 2026年10月8日更新于 2026年10月8日仓库8个月前更新

Headless utilities for building range and multi-range sliders in TS/JS, React, Vue, Solid, Svelte & Angular.

仅含说明Software Development
AI 生成的概览

TanStack Ranger 参考指南，介绍用于在 TS/JS 框架中构建无障碍范围与多范围滑块的 headless 工具。

功能
说明 TanStack Ranger 这一 headless 滑块库，涵盖安装、useRanger hook、必填与可选选项，以及 ranger 实例和 handle API。给出单值、范围和多滑块、自定义步进、刻度标记与对数刻度的代码示例。还涉及无障碍属性、受控用法、样式建议、框架适配、最佳实践和常见陷阱。
适用场景
在 React、Vue、Solid、Svelte 或 Angular 中使用 TanStack Ranger 实现范围或多范围滑块组件时使用。适合需要 headless 滑块逻辑、无障碍滑块手柄、自定义步进或刻度，或非线性数值刻度的情况。
运行要求
仅为说明文档，不附带脚本。按示例操作需要 Node.js 与 npm 来安装 @tanstack/react-ranger 或对应框架的包，并需要受支持的框架，如 React、Vue、Solid、Svelte 或 Angular。

Overview

TanStack Ranger provides headless utilities for building fully accessible range and multi-range slider components. It handles all the complex logic for single value, range, and multi-thumb sliders while giving you complete control over styling and markup.

Package: @tanstack/react-ranger Core: @tanstack/ranger-core (framework-agnostic) Status: Stable

Installation

bash
npm install @tanstack/react-ranger

Core Pattern

tsx
import { useRanger } from '@tanstack/react-ranger'
function RangeSlider() {  const [values, setValues] = useState([25, 75])
  const rangerInstance = useRanger({    getRangerElement: () => rangerRef.current,    values,    min: 0,    max: 100,    stepSize: 1,    onChange: (instance) => setValues(instance.sortedValues),  })
  const rangerRef = useRef<HTMLDivElement>(null)
  return (    <div      ref={rangerRef}      style={{        position: 'relative',        height: '8px',        background: '#ddd',        borderRadius: '4px',        width: '100%',      }}    >      {/* Track segments */}      {rangerInstance.getSteps().map(({ left, width }, i) => (        <div          key={i}          style={{            position: 'absolute',            left: `${left}%`,            width: `${width}%`,            height: '100%',            background: i === 1 ? '#3b82f6' : '#ddd',            borderRadius: '4px',          }}        />      ))}
      {/* Thumbs */}      {rangerInstance.handles.map((handle, i) => (        <button          key={i}          {...handle.getHandleProps()}          style={{            position: 'absolute',            left: `${handle.getPercentage()}%`,            transform: 'translateX(-50%)',            width: '20px',            height: '20px',            borderRadius: '50%',            background: '#3b82f6',            border: '2px solid white',            cursor: 'grab',          }}        />      ))}    </div>  )}

Ranger Options

Required

OptionTypeDescription
getRangerElement() => Element | nullReturns the slider track element
valuesnumber[]Current thumb values
minnumberMinimum value
maxnumberMaximum value
onChange(instance) => voidCalled when values change

Optional

OptionTypeDefaultDescription
stepSizenumber1Step increment between values
stepsnumber[]-Custom step positions (overrides stepSize)
tickSizenumber-Size of tick marks
ticksnumber[]-Custom tick positions
interpolatorInterpolatorlinearValue interpolation function
onDrag(instance) => void-Called during drag operations

Ranger Instance API

typescript
// Get sorted values (always ascending order)rangerInstance.sortedValues: number[]
// Get handles for rendering thumbsrangerInstance.handles: Handle[]
// Get track segments between handlesrangerInstance.getSteps(): { left: number; width: number }[]
// Get tick marksrangerInstance.getTicks(): { value: number; percentage: number }[]
// Programmatically set valuesrangerInstance.setValues(newValues: number[])

Handle API

typescript
interface Handle {  // Get percentage position on track (0-100)  getPercentage(): number
  // Get the current value  getValue(): number
  // Get props to spread on handle element  getHandleProps(): {    role: 'slider'    tabIndex: number    'aria-valuemin': number    'aria-valuemax': number    'aria-valuenow': number    onKeyDown: (e: KeyboardEvent) => void    onMouseDown: (e: MouseEvent) => void    onTouchStart: (e: TouchEvent) => void  }}

Single Value Slider

tsx
function SingleSlider() {  const [values, setValues] = useState([50])
  const rangerInstance = useRanger({    getRangerElement: () => rangerRef.current,    values,    min: 0,    max: 100,    stepSize: 1,    onChange: (instance) => setValues(instance.sortedValues),  })
  const rangerRef = useRef<HTMLDivElement>(null)
  return (    <div ref={rangerRef} className="slider-track">      {rangerInstance.handles.map((handle, i) => (        <button key={i} {...handle.getHandleProps()} className="slider-thumb">          {handle.getValue()}        </button>      ))}    </div>  )}

Multi-Range Slider

tsx
function MultiRangeSlider() {  const [values, setValues] = useState([10, 40, 60, 90])
  const rangerInstance = useRanger({    getRangerElement: () => rangerRef.current,    values,    min: 0,    max: 100,    stepSize: 5,    onChange: (instance) => setValues(instance.sortedValues),  })
  const rangerRef = useRef<HTMLDivElement>(null)
  return (    <div ref={rangerRef} className="slider-track">      {rangerInstance.getSteps().map(({ left, width }, i) => (        <div          key={i}          className={`segment ${i % 2 === 1 ? 'active' : ''}`}          style={{ left: `${left}%`, width: `${width}%` }}        />      ))}      {rangerInstance.handles.map((handle, i) => (        <button key={i} {...handle.getHandleProps()} className="slider-thumb" />      ))}    </div>  )}

Custom Steps

tsx
const rangerInstance = useRanger({  getRangerElement: () => rangerRef.current,  values,  min: 0,  max: 100,  steps: [0, 10, 25, 50, 75, 100], // Only these values allowed  onChange: (instance) => setValues(instance.sortedValues),})

Tick Marks

tsx
function SliderWithTicks() {  const rangerInstance = useRanger({    getRangerElement: () => rangerRef.current,    values,    min: 0,    max: 100,    stepSize: 10,    ticks: [0, 25, 50, 75, 100],    onChange: (instance) => setValues(instance.sortedValues),  })
  return (    <div>      <div ref={rangerRef} className="slider-track">        {/* Handles */}      </div>      <div className="tick-container">        {rangerInstance.getTicks().map((tick, i) => (          <div            key={i}            style={{ left: `${tick.percentage}%` }}            className="tick"          >            <span className="tick-label">{tick.value}</span>          </div>        ))}      </div>    </div>  )}

Logarithmic Scale

tsx
import { logarithmicInterpolator } from '@tanstack/react-ranger'
const rangerInstance = useRanger({  getRangerElement: () => rangerRef.current,  values,  min: 1,  max: 1000,  interpolator: logarithmicInterpolator,  onChange: (instance) => setValues(instance.sortedValues),})

Accessibility

TanStack Ranger provides built-in accessibility:

  • role="slider" on handles
  • aria-valuemin, aria-valuemax, aria-valuenow attributes
  • Keyboard navigation (Arrow keys, Home, End, Page Up/Down)
  • Focus management
tsx
// Add aria-label for screen readers<button  {...handle.getHandleProps()}  aria-label={`Value: ${handle.getValue()}`}/>

Controlled vs Uncontrolled

tsx
// Controlled (recommended)const [values, setValues] = useState([50])const ranger = useRanger({  values,  onChange: (instance) => setValues(instance.sortedValues),  // ...})
// With validationconst handleChange = (instance) => {  const [min, max] = instance.sortedValues  // Ensure minimum gap of 10  if (max - min >= 10) {    setValues(instance.sortedValues)  }}

Styling Tips

css
/* Track */.slider-track {  position: relative;  height: 8px;  background: #e5e7eb;  border-radius: 4px;  width: 100%;}
/* Active segment */.segment.active {  background: #3b82f6;}
/* Thumb */.slider-thumb {  position: absolute;  transform: translateX(-50%);  width: 20px;  height: 20px;  border-radius: 50%;  background: #3b82f6;  border: 2px solid white;  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);  cursor: grab;}
.slider-thumb:active {  cursor: grabbing;}
.slider-thumb:focus {  outline: none;  box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.3);}

Framework Adapters

FrameworkPackageStatus
React@tanstack/react-rangerStable
Vue@tanstack/vue-rangerStable
Solid@tanstack/solid-rangerStable
Svelte@tanstack/svelte-rangerStable
Angular@tanstack/angular-rangerStable
Core@tanstack/ranger-coreStable

Best Practices

  1. Always use sortedValues from onChange - handles may cross during drag
  2. Memoize getRangerElement callback to prevent unnecessary re-renders
  3. Use semantic HTML - render handles as <button> elements for accessibility
  4. Add aria-label to describe each handle's purpose
  5. Use CSS transforms (translateX) for positioning instead of left for better performance
  6. Validate in onChange to enforce constraints (min gap, max range, etc.)
  7. Use onDrag for real-time feedback during drag operations
  8. Consider touch targets - make handles at least 44x44px on mobile

Common Pitfalls

  • Forgetting position: relative on the track container
  • Using values instead of sortedValues (handles can swap positions)
  • Not providing getRangerElement as a callback
  • Setting thumb position with left instead of transform: translateX()
  • Forgetting to handle keyboard navigation (built-in via getHandleProps)
  • Not accounting for thumb width when calculating positions

来源与署名

来源：tanstack-skills/tanstack-skills位于plugins/tanstack-ranger/skills/tanstack-ranger提交6f5521e

许可证： 无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

更多来自 tanstack-skills/tanstack-skills 的技能

Tanstack Virtual

tanstack-skills

TanStack Virtual 参考指南，涵盖列表、网格和窗口虚拟化的 API 与用法模式。

Software Development358个月前更新

Tanstack Table

tanstack-skills

使用 TanStack Table 库在 TypeScript 和 JavaScript 中构建无头数据表格与数据网格的参考指南。

Software Development358个月前更新

Tanstack Store

tanstack-skills

TanStack Store 使用参考：跨框架响应式状态库，涵盖 store、派生值、副作用、批量更新与各框架适配器。

Software Development358个月前更新

Tanstack Start

tanstack-skills

TanStack Start 全栈 React 框架参考指南，涵盖服务器函数、中间件、API 路由、SSR 与部署。

Software Development358个月前更新

Tanstack Router

tanstack-skills

在 React 和 Solid 应用中使用 TanStack Router 构建类型安全路由的参考指南。

Software Development358个月前更新

Tanstack Query

tanstack-skills

关于使用 TanStack Query v5 在 TS/JS 应用中管理服务端状态、缓存与数据获取的参考指南。

Software Development358个月前更新

更多Software Development技能

Playground

anthropics

精选

构建自包含的交互式 HTML 演练场，包含控件、实时预览和可复制的提示词输出。

Software Development37K今天更新

M5 Onboard

anthropics

精选

通过 USB 检测 M5Stack ESP32 开发板，刷写 UIFlow 2.0 固件并安装 MicroPython 应用包。

Software Development37K今天更新

Cardputer Buddy

anthropics

精选

指导迭代 Cardputer-Adv 的 MicroPython 应用包：添加应用、通过 USB 串口推送文件、查看日志并运行 REPL 命令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精选

依据从远程来源获取的 Web Interface Guidelines 审查 UI 代码，并以 file:line 形式报告问题。

Software Development32K5周前更新

Vercel React Native Skills

vercel-labs

精选

React Native 与 Expo 最佳实践规则，涵盖列表性能、动画、导航、UI 模式、状态与 monorepo 配置。

Software Development32K5周前更新

Vercel React Best Practices

vercel-labs

精选

Vercel 的 React 与 Next.js 性能指南，以 70 条规则的形式用于编写、审查和重构代码。

Software Development32K5周前更新