Slider - Kumo

Price range

import { Slider } from "@cloudflare/kumo";

export function SliderRangeDemo() {
  return (
    <Slider
      label="Price range"
      defaultValue={[25, 75]}
      getAriaLabel={(index) =>
        index === 0 ? "Minimum price" : "Maximum price"
      }
      className="w-72"
    />
  );
}

安装

桶式导出

import { Slider } from "@cloudflare/kumo";

细粒度导入

import { Slider } from "@cloudflare/kumo/components/slider";

用法

import { Slider } from "@cloudflare/kumo";

export default function Example() {
  return <Slider label="Volume" defaultValue={40} />;
}

Slider 基于 Base UI 的 Slider 构建。value、defaultValue、min、max、step、format 和 onValueChange 等属性会传递给底层组件。

示例

基础滑块

单个滑块，其下方的徽章中显示数值，两端分别显示最小值和最大值。

Volume

import { Slider } from "@cloudflare/kumo";

export function SliderBasicDemo() {
  return <Slider label="Volume" defaultValue={40} className="w-72" />;
}

范围

向 value 或 defaultValue 传入数组，即可为每个数值渲染一个滑块。使用 getAriaLabel 为每个滑块提供独立的无障碍名称。

Price range

import { Slider } from "@cloudflare/kumo";

export function SliderRangeDemo() {
  return (
    <Slider
      label="Price range"
      defaultValue={[25, 75]}
      getAriaLabel={(index) =>
        index === 0 ? "Minimum price" : "Maximum price"
      }
      className="w-72"
    />
  );
}

自定义范围和步长

设置 min、max 和 step 以约束数值。

Match count

import { Slider } from "@cloudflare/kumo";

export function SliderStepDemo() {
  return (
    <Slider label="Match count" defaultValue={2} max={5} className="w-72" />
  );
}

格式化数值

format 接受 Intl.NumberFormat 选项，并应用于徽章、范围标签以及向辅助技术宣告的数值。

Sampling rate

import { Slider } from "@cloudflare/kumo";

export function SliderFormatDemo() {
  return (
    <Slider
      label="Sampling rate"
      defaultValue={0.25}
      min={0}
      max={1}
      step={0.05}
      format={{ style: "percent" }}
      className="w-72"
    />
  );
}

尺寸

在紧凑布局中使用 size="sm"。

Small

Base

import { Slider } from "@cloudflare/kumo";

export function SliderSizesDemo() {
  return (
    <div className="flex w-72 flex-col gap-6">
      <Slider label="Small" size="sm" defaultValue={30} />
      <Slider label="Base" defaultValue={30} />
    </div>
  );
}

受控

传入 value 和 onValueChange 以控制滑块。

Brightness

Brightness: 50%

import { useState } from "react";
import { Slider } from "@cloudflare/kumo";

export function SliderControlledDemo() {
  const [value, setValue] = useState(50);

  return (
    <div className="flex w-72 flex-col gap-3">
      <Slider
        label="Brightness"
        value={value}
        onValueChange={(next) => setValue(next)}
      />
      <p className="text-sm text-kumo-subtle">Brightness: {value}%</p>
    </div>
  );
}

禁用

Locked

import { Slider } from "@cloudflare/kumo";

export function SliderDisabledDemo() {
  return <Slider label="Locked" defaultValue={70} disabled className="w-72" />;
}

无障碍

每个滑块都是原生 range 输入，因此默认支持方向键、Page Up/Page Down 以及 Home/End。
label 为滑块及其滑标提供名称。没有可见标签时，请传入 getAriaLabel。
数值徽章和范围标签对辅助技术隐藏，因为每个滑块已经会宣告其格式化后的数值。

API 参考

Prop	Type	Default	Description
size	`"sm" \| "base"`	`"base"`	-
label	`ReactNode`	-	显示在滑块轨道上方的标签。
getAriaLabel	`(index: number) => string`	-	每个滑块的无障碍名称。在没有可见的 `label` 时使用，或用于区分范围滑块中的各个滑块。
value	`number \| readonly number[]`	-	受控值。传入数组可为每个数值渲染一个滑块（范围）。
defaultValue	`number \| readonly number[]`	-	非受控的初始值。传入数组可为每个数值渲染一个滑块（范围）。
onValueChange	`(value: number \| readonly number[], eventDetails: SliderRoot.ChangeEventDetails) => void`	-	在拖动期间或通过键盘更改值时调用
min	`number`	-	滑块的最小值（默认：0）
max	`number`	-	滑块的最大值（默认：100）
step	`number`	-	每步数值变化的幅度（默认：1）
format	`Intl.NumberFormatOptions`	-	格式化数值徽章、范围标签以及向辅助技术宣告的数值
disabled	`boolean`	-	滑块是否被禁用