Slider

A slider allows a user to select one or more values within a range.


Installation

npx nextui-cli@latest add slider
The above command is for individual installation only. You may skip this step if @nextui-org/react is already installed globally.

Import

Usage

Disabled

Sizes

Radius

Colors

Vertical Slider

It is possible to change the orientation of the slider by using the orientation="vertical" prop.

With Visible Steps

You can use the showSteps prop to display small dots on each step.

With Marks

You can use the marks prop to display a label on each step.

Range Slider

If you pass an array of values to the value prop or to the defaultValue prop, the slider will become a range slider.

Fill Offset

The fillOffset prop allows you to set where the fill should start.

With Tooltip

The showTooltip prop allows you to show a tooltip with the current thumb value when the user hovers or drags the thumb.

Note: You can change any of the tooltip props by passing the tooltipProps to the Slider component.

With Outline

It is possible to add a small outline to the slider's thumbs by passing the showOutline prop.

Start & End Content

Slider component provides startContent and endContent props that allows you to add any ReactNode to the start and end of the slider.

Value Formatting

Values are formatted as a percentage by default, but this can be modified by using the formatOptions prop to specify a different format. formatOptions is compatible with the option parameter of Intl.NumberFormat and is applied based on the current locale.

Note: Use the tooltipValueFormatOptions prop to format the tooltip value.

It is also possible to format the value using the getValue prop.

Hiding the Value

The Slider value is shown by default, but can be hidden by passing the hideValue prop.

Hiding the Thumbs

The Slider thumbs are shown by default, but can be hidden by passing the hideThumb prop.

Controlled

You can control the slider by passing the value and onChange props.

If you want to capture the slider value only when the user stops dragging the thumb, you can use the onChangeEnd prop.

Controlled Range

You can also control the range slider by using an array of values in the value and onChange props.

Custom Thumb

The Slider component provides a renderThumb prop that allows you to customize the thumb in any way you want.

Custom Range Thumbs

You can also use the renderThumb prop to customize the thumbs of a range slider. The index prop will tell you which thumb is being rendered.

Custom Label

The Slider component provides a renderLabel prop that allows you to customize the label in any way you want.

Custom Value

The Slider component provides a renderValue prop that allows you to customize the value label element.

Disabling Thumb Scale

In case you want to disable the thumb scale animation, you can pass the disableThumbScale prop.

Slots

  • base: The foundational slot, encompassing all other slots and elements. It serves as the primary container.
  • labelWrapper: The container for the Slider's label and value. It aligns these elements and ensures a consistent layout.
  • label: A dedicated slot to display the Slider's label.
  • value: Displays the current value of the Slider. Located within the labelWrapper.
  • step: Represents individual steps or intervals on the Slider.
  • mark: Denotes specific values or intervals along the Slider.
  • trackWrapper: A container for the slider's track, ensuring it is consistently aligned and positioned.
  • track: The base bar of the Slider, along which the thumb moves.
  • filler: A visual representation of the selected value, filling the track from the start point to the current thumb position.
  • thumb: The interactive element that users drag along the track to select a value on the Slider.
  • startContent: A slot for additional content or icons at the beginning of the Slider.
  • endContent: A slot for additional content or icons at the end of the Slider.

Custom Styles

You can customize the Slider component by passing custom Tailwind CSS classes to the component slots.

Data Attributes

Slider has the following attributes:

  • data-hover: When the slider is being hovered. Based on useHover
  • data-orientation: The orientation of the slider. Based on orientation prop.

Thumbs have the following attributes which are returned by the renderThumb prop:

  • data-dragging: When the thumb is being dragged.
  • data-focus-visible: When the thumb is focused. Based on useFocusVisible
  • data-hover: When the thumb is being hovered. Based on useHover
  • data-pressed: When the thumb is being pressed. Based on usePress

Accessibility

  • Support for one or multiple thumbs.
  • Support for mouse, touch, and keyboard via the useMove hook.
  • Multi-touch support for dragging multiple thumbs or multiple sliders at once.
  • Pressing on the track moves the nearest thumb to that position.
  • Supports using the arrow keys, as well as page up/down, home, and end keys.
  • Support for both horizontal and vertical orientations.
  • Support for custom min, max, and step values with handling for rounding errors.
  • Support for disabling the whole slider or individual thumbs.
  • Prevents text selection while dragging.
  • Exposed to assistive technology as a group of slider elements via ARIA.
  • Slider thumbs use hidden native input elements to support touch screen readers.
  • Support for labeling both the slider as a whole and individual thumbs.
  • Support for displaying the current thumb values using an <output> element.
  • Internationalized number formatting as a percentage or value.
  • Support for mirroring in RTL locales.

API

Slider Props

AttributeTypeDescriptionDefault
labelReactNodeThe content to display as the label.-
namestringThe name of the input element, used when submitting an HTML form. See MDN.-
sizesm | md | lgThe size of the Slider filler and thumb.md
colorforeground | primary | secondary | success | warning | dangerThe color of the filler and thumb.primary
radiusnone | sm | md | lg | fullThe Slider's thumbs border radius.full
stepnumberThe Slider's step value.1
valuenumberThe current value (controlled).-
defaultValuenumberThe default value (uncontrolled).-
minValuenumberThe slider's minimum value.0
maxValuenumberThe slider's maximum value.100
orientationhorizontal | verticalThe orientation of the Slider.horizontal
fillOffsetnumberThe offset from which to start the fill.-
showStepsbooleanWhether to show the steps indicators.false
showTooltipbooleanWhether to show a tooltip with the current thumb value when the user hovers or drags the thumb.false
marksSliderStepMarksThe marks to display on the Slider's steps.-
startContentReactNodeThe content to display at the beginning of the Slider.-
endContentReactNodeThe content to display at the end of the Slider.-
formatOptionsIntl.NumberFormatThe options to format the value.-
tooltipValueFormatOptionsIntl.NumberFormatThe options to format the tooltip value. By default, it uses the same options as formatOptions.-
tooltipPropsTooltipPropsThe props to pass to the thumbs's tooltip.-
showOutlinebooleanWhether to show a small outline around the thumbs.false
hideValuebooleanWhether to hide the Slider value.false
hideThumbbooleanWhether to hide all the Slider thumbs.false
disableThumbScalebooleanWhether to disable the thumb scale animation.false
isDisabledbooleanWhether the whole Slider is disabled.false
disableAnimationbooleanWhether to disable the Slider animations.false
classNamesRecord<"base"|"labelWrapper"|"label"| "value" | "step" | "mark" | "trackWrapper" | "track"| "output" | "filler" | "thumb" | "startContent" | "endContent", string>Allows to set custom class names for the Slider slots.-

Slider Functions

NameTypeDescription
getValue(value: SliderValue) => stringA function to format the value. Overrides default formatted number.
renderLabel(props: DOMAttributes<HTMLLabelElement>) => ReactNodeA function to render the label.
renderValue(props: DOMAttributes<HTMLOutputElement>) => ReactNodeA function to render the value.
renderThumb(props: DOMAttributes<HTMLDivElement> & {index?: number}) => ReactNodeA function to render the thumbs. The index prop will tell you which thumb is being rendered.

Slider Events

NameTypeDescription
onChange(value: SliderValue) => voidCallback fired when the value changes.
onChangeEnd(value: SliderValue) => voidCallback fired when the value changes and the user stops dragging the thumb.

Types

Slider Value

export type SliderValue = number | number[];

Slider Step Marks

export type SliderStepMarks = {
value: number;
label: string;
}[];