用法

import { Slider } from '@heroui/react';

音量30

组件结构

import { Slider, Label } from '@heroui/react';

export default () => (
  <Slider>
    <Label />
    <Slider.Output />
    <Slider.Track>
      <Slider.Fill />
      <Slider.Thumb />
    </Slider.Track>
  </Slider>
)

示例

禁用

音量30

范围滑块结构

import { Slider, Label } from '@heroui/react';

export default () => (
  <Slider defaultValue={[25, 75]}>
    <Label />
    <Slider.Output />
    <Slider.Track>
      {({state}) => (
        <>
          <Slider.Fill />
          {state.values.map((_, i) => (
            <Slider.Thumb key={i} index={i} />
          ))}
        </>
      )}
    </Slider.Track>
  </Slider>
)

垂直方向

音量30

范围选择

价格区间$100.00 – $500.00

受控数值

使用 value 和 onChange 控制数值。

音量25

当前数值：25

自定义数值格式

使用 formatOptions 格式化显示的数值。此示例将数值格式化为美元。

价格$60.00

自定义输出展示

自定义 Slider.Output，控制已选数值的展示方式。

区间25 – 75

渲染函数

音量30

自定义样式

Tailwind CSS

亮度40

全局 CSS

若要自定义组件类，可使用 @layer components 指令。了解更多。

@layer components {
  .slider {
    @apply flex flex-col gap-2;
  }

  .slider__output {
    @apply text-muted-fg text-sm;
  }

  .slider-track {
    @apply relative h-2 w-full rounded-full bg-surface-secondary;
  }

  .slider-fill {
    @apply absolute h-full rounded-full bg-accent;
  }

  .slider-thumb {
    @apply size-4 rounded-full bg-accent border-2 border-background;
  }
}

样式参考

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

Slider 组件使用以下 CSS 类（查看源码样式）：

基础类

.slider - Slider 根容器
.slider__output - 显示当前值的输出元素
.slider-track - 包含填充与滑块的轨道元素
.slider-fill - 显示已选范围的填充元素
.slider-thumb - 单个滑块控制点

状态类

.slider[data-disabled="true"] - 禁用状态
.slider[data-orientation="vertical"] - 纵向方向
.slider-thumb[data-dragging="true"] - 滑块正在拖动
.slider-thumb[data-focus-visible="true"] - 滑块键盘聚焦
.slider-thumb[data-disabled="true"] - 滑块禁用状态
.slider-track[data-fill-start="true"] - 填充从起点开始
.slider-track[data-fill-end="true"] - 填充在终点结束

交互状态

该组件同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制：

悬停：滑块上的 :hover 或 [data-hovered="true"]
聚焦：滑块上的 :focus-visible 或 [data-focus-visible="true"]
拖动：滑块上的 [data-dragging="true"]
禁用：Slider 或滑块上的 :disabled 或 [data-disabled="true"]

API 参考

Slider

Prop	类型	默认值	描述
`value`	`number \| number[]`	-	当前值（受控）。
`defaultValue`	`number \| number[]`	-	默认值（非受控）。
`onChange`	`(value: number \| number[]) => void`	-	值变化时的事件处理函数。
`onChangeEnd`	`(value: number \| number[]) => void`	-	拖动结束时的事件处理函数。
`minValue`	`number`	`0`	Slider 的最小值。
`maxValue`	`number`	`100`	Slider 的最大值。
`step`	`number`	`1`	Slider 的步进值。
`formatOptions`	`Intl.NumberFormatOptions`	-	数值标签的显示格式。
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	Slider 的方向。
`isDisabled`	`boolean`	-	Slider 是否禁用。
`aria-label`	`string`	-	Slider 的无障碍标签。
`aria-labelledby`	`string`	-	标注 Slider 的元素 ID。
`className`	`string`	-	额外的 CSS 类。
`children`	`ReactNode \| RenderFunction`	-	Slider 内容或渲染函数。
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderRenderProps>`	-	使用自定义渲染函数覆盖默认 DOM 元素。

Slider.Output

Prop	类型	默认值	描述
`className`	`string`	-	额外的 CSS 类。
`children`	`ReactNode \| RenderFunction`	-	输出内容或渲染函数。
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderOutputRenderProps>`	-	使用自定义渲染函数覆盖默认 DOM 元素。

Slider.Track

Prop	类型	默认值	描述
`className`	`string`	-	额外的 CSS 类。
`children`	`ReactNode \| RenderFunction`	-	轨道内容或渲染函数。
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderTrackRenderProps>`	-	使用自定义渲染函数覆盖默认 DOM 元素。

Slider.Fill

Prop	类型	默认值	描述
`className`	`string`	-	额外的 CSS 类。
`style`	`CSSProperties`	-	行内样式。

Slider.Thumb

Prop	类型	默认值	描述
`index`	`number`	`0`	滑块在 Slider 内的索引。
`isDisabled`	`boolean`	-	该滑块是否禁用。
`name`	`string`	-	输入元素名称，用于提交 HTML 表单。
`className`	`string`	-	额外的 CSS 类。
`children`	`ReactNode \| RenderFunction`	-	滑块内容或渲染函数。
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderThumbRenderProps>`	-	使用自定义渲染函数覆盖默认 DOM 元素。

RenderProps

对 Slider.Output 或 Slider.Track 使用渲染函数时，会提供以下值：

Prop	类型	描述
`state`	`SliderState`	Slider 的状态。
`values`	`number[]`	按滑块索引管理的数值。
`getThumbValueLabel`	`(index: number) => string`	返回指定滑块数值的字符串标签。
`orientation`	`"horizontal" \| "vertical"`	Slider 的方向。
`isDisabled`	`boolean`	Slider 是否禁用。