The static string to use used for `aria-label` if no visible label is used.
Slider
The Slider is used to allow users to make selections from a range of values.
Import#
Chakra UI exports 5 components for Slider:
Slider
: The wrapper that provides context and functionality for all children.SliderTrack
: The empty part of the slider that shows the track.SliderFilledTrack
: The filled part of the slider.SliderThumb
: The handle that's used to change the slider value.SliderMark
: The label or mark that shows names for specific slider values
import {Slider,SliderTrack,SliderFilledTrack,SliderThumb,SliderMark,} from '@chakra-ui/react'
Usage#
Sliders reflect a range of values along a bar, from which users may select a single value. They are ideal for adjusting settings such as volume, brightness, or applying image filters.
Note: We recommend adding a
aria-label
oraria-labelledby
prop to provide an accessible label for the Slider.
<Slider aria-label='slider-ex-1' defaultValue={30}><SliderTrack><SliderFilledTrack /></SliderTrack><SliderThumb /></Slider>
Changing the slider color scheme#
<Slider aria-label='slider-ex-2' colorScheme='pink' defaultValue={30}><SliderTrack><SliderFilledTrack /></SliderTrack><SliderThumb /></Slider>
Changing the slider orientation#
<Slideraria-label='slider-ex-3'defaultValue={30}orientation='vertical'minH='32'><SliderTrack><SliderFilledTrack /></SliderTrack><SliderThumb /></Slider>
Customizing the Slider#
Slider
component was designed to be composed to make it easy for you to
customize its styles.
<Slider aria-label='slider-ex-4' defaultValue={30}><SliderTrack bg='red.100'><SliderFilledTrack bg='tomato' /></SliderTrack><SliderThumb boxSize={6}><Box color='tomato' as={MdGraphicEq} /></SliderThumb></Slider>
Discrete Sliders#
Discrete sliders allow you to snap to predefined sets of values. This can be
accomplished using the step
prop.
<Slider defaultValue={60} min={0} max={300} step={30}><SliderTrack bg='red.100'><SliderFilledTrack bg='tomato' /></SliderTrack><SliderThumb boxSize={6} /></Slider>
Slider with custom labels and marks#
You can have custom labels and marks by using SliderMark
component
function SliderMarkExample() {const [sliderValue, setSliderValue] = useState(50)const labelStyles = {mt: '2',ml: '-2.5',fontSize: 'sm',}return (<Box p={4} pt={6}><Slider aria-label='slider-ex-6' onChange={(val) => setSliderValue(val)}><SliderMark value={25} {...labelStyles}>25%</SliderMark><SliderMark value={50} {...labelStyles}>50%</SliderMark><SliderMark value={75} {...labelStyles}>75%</SliderMark><SliderMarkvalue={sliderValue}textAlign='center'bg='blue.500'color='white'mt='-10'ml='-5'w='12'>{sliderValue}%</SliderMark><SliderTrack><SliderFilledTrack /></SliderTrack><SliderThumb /></Slider></Box>)}
And you can also use Tooltip
with SliderThumb
function SliderThumbWithTooltip() {const [sliderValue, setSliderValue] = React.useState(5)const [showTooltip, setShowTooltip] = React.useState(false)return (<Sliderid='slider'defaultValue={5}min={0}max={100}colorScheme='teal'onChange={(v) => setSliderValue(v)}onMouseEnter={() => setShowTooltip(true)}onMouseLeave={() => setShowTooltip(false)}><SliderMark value={25} mt='1' ml='-2.5' fontSize='sm'>25%</SliderMark><SliderMark value={50} mt='1' ml='-2.5' fontSize='sm'>50%</SliderMark><SliderMark value={75} mt='1' ml='-2.5' fontSize='sm'>75%</SliderMark><SliderTrack><SliderFilledTrack /></SliderTrack><TooltiphasArrowbg='teal.500'color='white'placement='top'isOpen={showTooltip}label={`${sliderValue}%`}><SliderThumb /></Tooltip></Slider>)}
Getting the final value when dragging the slider#
Dragging the slider can trigger lots of updates and the user might only be
interested in the final result after sliding is complete. You can use
onChangeEnd
for this.
<Slider aria-label='slider-ex-5' onChangeEnd={(val) => console.log(val)}><SliderTrack><SliderFilledTrack /></SliderTrack><SliderThumb /></Slider>
Configure thumb focus with focusThumbOnChange
#
By default SliderThumb
will receive focus whenever value
changes. You can
opt-out of this behavior by setting the value of focusThumbOnChange
to
false
. This is normally used with a "controlled" slider value.
<Slider aria-label='slider-ex-5' value={value} focusThumbOnChange={false}><SliderTrack><SliderFilledTrack /></SliderTrack><SliderThumb /></Slider>
useSlider#
The useSlider
hook is exported with state and focus management logic for use
in creating tailor-made slider component for your application. Read more about
the useSlider
hook here.
Props#
Slider Props#
The Slider
component wraps all its children in the Box
component, so you can pass all Box
props to change its style.
aria-label
aria-label
string
aria-labelledby
aria-labelledby
The static string `aria-labelledby` that points to the ID of the element that serves as label for the slider
string
aria-valuetext
aria-valuetext
The static string to use used for `aria-valuetext`
string
colorScheme
colorScheme
The visual color appearance of the component
"whiteAlpha" | "blackAlpha" | "gray" | "red" | "orange" | "yellow" | "green" | "teal" | "blue" | "cyan" | "purple" | "pink"
blue
defaultValue
defaultValue
The initial value of the slider in uncontrolled mode
number
direction
direction
The writing mode
"ltr" | "rtl"
ltr
focusThumbOnChange
focusThumbOnChange
If false
, the slider handle will not capture focus when value changes.
boolean
true
getAriaValueText
getAriaValueText
Function that returns the `aria-valuetext` for screen readers. It is mostly used to generate a more human-readable representation of the value for assistive technologies
(value: number) => string
id
id
The base id
to use for the slider and its components
string
isDisabled
isDisabled
If true
, the slider will be disabled
boolean
false
isReadOnly
isReadOnly
If true
, the slider will be in `read-only` state
boolean
false
isReversed
isReversed
If true
, the value will be incremented or decremented in reverse.
boolean
max
max
The maximum allowed value of the slider. Cannot be less than min.
number
100
min
min
The minimum allowed value of the slider. Cannot be greater than max.
number
0
name
name
The name attribute of the hidden input
field.
This is particularly useful in forms
string
onChange
onChange
Function called whenever the slider value changes (by dragging or clicking)
(value: number) => void
onChangeEnd
onChangeEnd
Function called when the user is done selecting a new value (by dragging or clicking)
(value: number) => void
onChangeStart
onChangeStart
Function called when the user starts selecting a new value (by dragging or clicking)
(value: number) => void
size
size
The size of the Slider
"lg" | "md" | "sm"
md
step
step
The step in which increments/decrements have to be made
number
1
value
value
The value of the slider in controlled mode
number
variant
variant
The variant of the Slider
string
SliderThumb Props#
SliderThumb
composes Box so you can pass all Box
props
to change its style.
SliderFilledTrack Props#
SliderFilledTrack
composes Box so you can pass all Box
props to change its style.
SliderTrack Props#
SliderTrack
composes Box so you can pass all Box
props
to change its style.
The Slider
component is a multipart component. The styling needs to be applied
to each part specifically.
To learn more about styling multipart components, visit the Component Style page.
Anatomy#
- A:
container
- B:
track
- C:
thumb
- D:
filledTrack
- E:
mark
Theming properties#
The properties that affect the theming of the Slider
component are:
size
: The size of the slider. Defaults tomd
.colorScheme
: The color scheme of the slider. Defaults toblue
.
Theming utilities#
createMultiStyleConfigHelpers
: a function that returns a set of utilities for creating style configs for a multipart component (definePartsStyle
anddefineMultiStyleConfig
).definePartsStyle
: a function used to create multipart style objects.defineMultiStyleConfig
: a function used to define the style configuration for a multipart component.
import { sliderAnatomy as parts } from '@chakra-ui/anatomy'import { createMultiStyleConfigHelpers } from '@chakra-ui/react'const { definePartsStyle, defineMultiStyleConfig } =createMultiStyleConfigHelpers(parts.keys)
Customizing the default theme#
import { sliderAnatomy as parts } from '@chakra-ui/anatomy'import { createMultiStyleConfigHelpers } from '@chakra-ui/react'const { definePartsStyle, defineMultiStyleConfig } =createMultiStyleConfigHelpers(parts.keys)const baseStyle = definePartsStyle({// define the part you're going to stylethumb: {bg: 'orange.400', // change the background of the thumb to orange.400},filledTrack: {bg: 'blue.600', // change the background of the filled track to blue.600},})export const sliderTheme = defineMultiStyleConfig({ baseStyle })
After customizing the slider theme, we can import it in our theme file and add
it in the components
property:
import { extendTheme } from '@chakra-ui/react'import { sliderTheme } from './theme/components/slider.ts'export const theme = extendTheme({components: { Slider: sliderTheme },})
This is a crucial step to make sure that any changes that we make to the slider theme are applied.
Adding a custom size#
Let's assume we want to include an extra large slider size. Here's how we can do that:
import { sliderAnatomy as parts } from '@chakra-ui/anatomy'import { createMultiStyleConfigHelpers } from '@chakra-ui/react'const { definePartsStyle, defineMultiStyleConfig } =createMultiStyleConfigHelpers(parts.keys)const sizes = {xl: definePartsStyle({container: defineStyle({w: "50%",}),track: defineStyle({h: 7,}),thumb: defineStyle({boxSize: 7,}),}),};export const sliderTheme = defineMultiStyleConfig({ sizes })// Now we can use the new `xl` size<Slider size="xl">...</Slider>
Every time you're adding anything new to the theme, you'd need to run the CLI command to get proper autocomplete in your IDE. You can learn more about the CLI tool here.
Creating a custom variant#
Let's assume we want to create a custom square variant. Here's how we can do that:
import { sliderAnatomy as parts } from '@chakra-ui/anatomy'import { createMultiStyleConfigHelpers } from '@chakra-ui/react'const { definePartsStyle, defineMultiStyleConfig } =createMultiStyleConfigHelpers(parts.keys)const square = definePartsStyle({thumb: defineStyle({rounded: "none",}),});export const sliderTheme = defineMultiStyleConfig({variants: { square },})// Now we can use the new `square` variant<Slider variant="square">...</Slider>
Changing the default properties#
Let's assume we want to change the default size and variant of every slider in our app. Here's how we can do that:
import { sliderAnatomy } from '@chakra-ui/anatomy'import { createMultiStyleConfigHelpers, defineStyle } from '@chakra-ui/react'const { defineMultiStyleConfig } = createMultiStyleConfigHelpers(sliderAnatomy.keys,)export const sliderTheme = defineMultiStyleConfig({defaultProps: {size: 'xl',variant: 'square',},})// This saves you time, instead of manually setting the size and variant every time you use a slider:<Slider size="xl" variant="square">...</Slider>
Showcase#
import { Slider, SliderTrack, SliderFilledTrack, SliderThumb, SliderMark, Text, Box, Flex, useColorMode, IconButton, } from "@chakra-ui/react"; import { useState } from "react"; import { FaMoon, FaSun } from "react-icons/fa"; export default function App() { const { toggleColorMode, colorMode } = useColorMode(); const [sliderValue, setSliderValue] = useState(50); return ( <> <Flex h={"100vh"} textAlign="center" gap={5} p={8} direction="column"> <Box display="flex" gap={3} flexDirection="column"> <Text fontSize="lg">Default variant</Text> <Slider aria-label="slider-ex-1"> <SliderTrack> <SliderFilledTrack /> </SliderTrack> <SliderThumb /> </Slider> </Box> <Box display="flex" gap={3} flexDirection="column"> <Text fontSize="lg">Custom size</Text> <Slider aria-label="slider-ex-1" size="xl"> <SliderTrack> <SliderFilledTrack /> </SliderTrack> <SliderThumb /> </Slider> </Box> <Box display="flex" gap={3} flexDirection="column"> <Text fontSize="lg">Square variant</Text> <Slider aria-label="slider-ex-1" variant="square"> <SliderTrack> <SliderFilledTrack /> </SliderTrack> <SliderThumb /> </Slider> </Box> <Box display="flex" gap={3} flexDirection="column"> <Text fontSize="lg">Custom variant with markers</Text> <Slider aria-label="slider-ex-1" variant="colorful" onChange={(val) => setSliderValue(val)}> <SliderMark value={sliderValue}> {sliderValue}% </SliderMark> <SliderTrack> <SliderFilledTrack /> </SliderTrack> <SliderThumb /> </Slider> </Box> <IconButton aria-label="toggle theme" rounded="full" size="xs" position="absolute" bottom={4} left={4} onClick={toggleColorMode} icon={colorMode === "dark" ? <FaSun /> : <FaMoon />} /> </Flex> </> ); }