ProComponents, templates & AI tooling
HeroUI
27.7k
快速开始
组件
发布说明
迁移

Slider 滑块

Slider 允许用户在范围内选择一个或多个值。

StorybookReact Aria源代码样式源代码

引入

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

用法

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

export function Default() {
  return (
    <Slider className="w-full max-w-xs" defaultValue={30}>

组件结构

引入 Slider 组件，并通过点语法访问各部分。

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

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

范围滑块组件结构

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
import {Label, Slider} from "@heroui/react";

export function Vertical() {
  return (
    <div className="flex h-64 items-center justify-center">

范围

$100.00 – $500.00
"use client";

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

export function Range() {

禁用

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

export function Disabled() {
  return (
    <Slider isDisabled className="w-full max-w-xs" defaultValue={30}>

自定义渲染函数

30
"use client";

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

export function CustomRenderFunction() {

样式

传入 Tailwind CSS 类

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

function CustomSlider() {
  return (
    <Slider className="w-full">
      <Label>Volume</Label>
      <Slider.Output className="text-muted-fg text-sm" />
      <Slider.Track className="h-2 rounded-full bg-surface-secondary">
        <Slider.Fill className="bg-accent" />
        <Slider.Thumb className="size-4 rounded-full bg-accent" />
      </Slider.Track>
    </Slider>
  );
}

自定义组件类

若要自定义 Slider 组件类，可以使用 @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 Props

Prop类型默认值描述
valuenumber | number[]-当前值（受控）。
defaultValuenumber | number[]-默认值（非受控）。
onChange(value: number | number[]) => void-值变化时的事件处理函数。
onChangeEnd(value: number | number[]) => void-拖动结束时的事件处理函数。
minValuenumber0Slider 的最小值。
maxValuenumber100Slider 的最大值。
stepnumber1Slider 的步进值。
formatOptionsIntl.NumberFormatOptions-数值标签的显示格式。
orientation"horizontal" | "vertical""horizontal"Slider 的方向。
isDisabledboolean-Slider 是否禁用。
aria-labelstring-Slider 的无障碍标签。
aria-labelledbystring-标注 Slider 的元素 ID。
classNamestring-额外的 CSS 类。
childrenReactNode | RenderFunction-Slider 内容或渲染函数。
renderDOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderRenderProps>-使用自定义渲染函数覆盖默认 DOM 元素。

Slider.Output Props

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

Slider.Track Props

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

Slider.Fill Props

Prop类型默认值描述
classNamestring-额外的 CSS 类。
styleCSSProperties-行内样式。

Slider.Thumb Props

Prop类型默认值描述
indexnumber0滑块在 Slider 内的索引。
isDisabledboolean-该滑块是否禁用。
namestring-输入元素名称，用于提交 HTML 表单。
classNamestring-额外的 CSS 类。
childrenReactNode | RenderFunction-滑块内容或渲染函数。
renderDOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderThumbRenderProps>-使用自定义渲染函数覆盖默认 DOM 元素。

RenderProps

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

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

示例

基础用法

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

<Slider defaultValue={30}>
  <Label>Volume</Label>
  <Slider.Output />
  <Slider.Track>
    <Slider.Fill />
    <Slider.Thumb />
  </Slider.Track>
</Slider>

范围滑块

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

<Slider
  defaultValue={[100, 500]}
  formatOptions={{style: "currency", currency: "USD"}}
  maxValue={1000}
  minValue={0}
  step={50}
>
  <Label>Price Range</Label>
  <Slider.Output />
  <Slider.Track>
    {({state}) => (
      <>
        <Slider.Fill />
        {state.values.map((_, i) => (
          <Slider.Thumb key={i} index={i} />
        ))}
      </>
    )}
  </Slider.Track>
</Slider>

受控值

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

function ControlledSlider() {
  const [value, setValue] = useState(25);

  return (
    <>
      <Slider value={value} onChange={setValue}>
        <Label>Volume</Label>
        <Slider.Output />
        <Slider.Track>
          <Slider.Fill />
          <Slider.Thumb />
        </Slider.Track>
      </Slider>
      <p>Current value: {value}</p>
    </>
  );
}

自定义数值格式

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

<Slider
  defaultValue={60}
  formatOptions={{style: "currency", currency: "USD"}}
>
  <Label>Price</Label>
  <Slider.Output />
  <Slider.Track>
    <Slider.Fill />
    <Slider.Thumb />
  </Slider.Track>
</Slider>

纵向方向

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

<Slider defaultValue={30} orientation="vertical" aria-label="Volume">
  <Label>Volume</Label>
  <Slider.Output />
  <Slider.Track>
    <Slider.Fill />
    <Slider.Thumb />
  </Slider.Track>
</Slider>

自定义输出展示

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

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

无障碍

Slider 组件实现 ARIA slider 模式，并提供：

  • 完整的键盘导航支持（方向键、Home、End、Page Up/Down）
  • 数值变化时的屏幕阅读器播报
  • 合理的焦点管理
  • 禁用状态支持
  • 通过隐藏 input 元素与 HTML 表单集成
  • 结合区域设置进行数值格式化的国际化支持
  • 从右到左（RTL）语言支持

更多信息见 React Aria Slider 文档。

Skeleton 骨架屏

Skeleton 用于展示加载状态，并预览组件的预期形状。

Spinner 加载指示器

用于展示等待或处理中状态的加载指示组件。

本页目录

引入用法组件结构范围滑块组件结构纵向范围禁用自定义渲染函数样式传入 Tailwind CSS 类自定义组件类CSS 类基础类状态类交互状态API 参考Slider PropsSlider.Output PropsSlider.Track PropsSlider.Fill PropsSlider.Thumb PropsRenderProps示例基础用法范围滑块受控值自定义数值格式纵向方向自定义输出展示无障碍