Slider | iTwinUI

Sliders let users make selections from a range of values.

import * as React from 'react';
import { Slider, Label, InputGrid } from '@itwin/itwinui-react';

export default () => {
  const labelId = React.useId();

  return (
    <InputGrid className='demo-input-grid'>
      <Label id={labelId} as='div'>
        Choose a value
      </Label>
      <Slider
        thumbProps={() => ({ 'aria-labelledby': labelId })}
        values={[50]}
        min={0}
        max={100}
      />
    </InputGrid>
  );
};

Sliders allow the user to graphically select a specific input value, or a range, within defined limits. Optionally, a tooltip appears above the slider handle to indicate the current value and changes as the slider handle is repositioned. The sliders min, max, and step values can be changed as needed. To help visually enforce incremental steps, you may optionally choose to display ticks underneath the slider. The slider can be oriented horizontally or vertically.

Changes made with sliders should be immediate, allowing a user to make slider adjustments until finding their preference. This means a setting controlled by a slider should not require to be validated by clicking a button for the changes to be applied.

Variants

Default

Use the default slider in most situations, when a simple gradation between numerical values is required. Numerical gradation between the two absolute values is optional.

Range

The range sliders should be used when the desired input is a range such as 25 through 75.

import * as React from 'react';
import { Slider, Label, InputGrid } from '@itwin/itwinui-react';

export default () => {
  const labelId = React.useId();

  return (
    <InputGrid className='demo-input-grid'>
      <Label id={labelId} as='div'>
        Choose a range
      </Label>
      <Slider
        thumbProps={() => ({ 'aria-labelledby': labelId })}
        values={[25, 75]}
        min={0}
        max={100}
      />
    </InputGrid>
  );
};

You can have multiple ranges and can also have the range wrap.

import * as React from 'react';
import { Slider, Label, InputGrid } from '@itwin/itwinui-react';

export default () => {
  const labelId = React.useId();

  return (
    <InputGrid className='demo-input-grid'>
      <Label id={labelId} as='div'>
        Choose ranges
      </Label>
      <Slider
        thumbProps={() => ({ 'aria-labelledby': labelId })}
        values={[20, 40, 60, 80]}
        min={0}
        max={100}
        thumbMode='allow-crossing'
        trackDisplayMode='even-segments'
      />
    </InputGrid>
  );
};

Vertical

The slider can be displayed horizontally (default) or vertically.

import * as React from 'react';
import { Slider } from '@itwin/itwinui-react';

export default () => {
  return (
    <Slider
      thumbProps={() => ({ 'aria-label': `Choose a value` })}
      values={[50]}
      orientation='vertical'
      className='demo-slider'
    />
  );
};

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.

Immediate effect

Changes made with sliders are immediate, allowing a user to make slider adjustments until finding their preference. This means a setting controlled by a slider should not require to be validated by clicking a button for the changes to be applied. They shouldn’t be paired with settings that have even minor delays in providing user feedback.

Current state

Sliders reflect the current state of the settings they control.

Labels & steps

You can display min / max labels as text or icons and can optionally enable tick labels underneath the slider. You can also have the value jump by a certain amount of steps - in this example it jumps by 10. To have more finer control, the jump can be changed to a decimal such as 0.5.

import * as React from 'react';
import { Slider, Label, InputGrid } from '@itwin/itwinui-react';

import {
  SvgSmileyHappyVery,
  SvgSmileySadVery,
} from '@itwin/itwinui-icons-react';

export default () => {
  const labelId = React.useId();

  return (
    <InputGrid className='demo-input-grid'>
      <Label id={labelId} as='div'>
        Choose a happiness level
      </Label>
      <Slider
        thumbProps={() => ({ 'aria-labelledby': labelId })}
        values={[50]}
        minLabel={<SvgSmileySadVery />}
        maxLabel={<SvgSmileyHappyVery />}
        tickLabels={['0', '20', '40', '60', '80', '100']}
        min={0}
        max={100}
        step={10}
      />
    </InputGrid>
  );
};

Custom thumb

The thumb can be customized if desired.

import * as React from 'react';
import { Slider } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <Slider
        values={[50]}
        min={0}
        max={100}
        thumbProps={() => {
          return {
            'aria-label': `Choose a value`,
            className: 'demo-thumb',
            children: <span className='demo-thumb-children'>|||</span>,
          };
        }}
      />
    </div>
  );
};

Tooltips

Tooltips are enabled by default but can be turned off.

import * as React from 'react';
import { Slider, Text, Label, InputGrid } from '@itwin/itwinui-react';

export default () => {
  const labelId = React.useId();

  const dateFormatter = React.useMemo(() => {
    return new Intl.DateTimeFormat('default', {
      month: 'short',
      day: '2-digit',
      timeZone: 'UTC',
    });
  }, []);

  const [currentValue, setCurrentValue] = React.useState({
    number: 1,
    date: new Date(Date.UTC(2019, 0, 1)),
  });

  const updateValue = React.useCallback((values) => {
    const newDate = new Date(Date.UTC(2019, 0, values[0]));
    setCurrentValue({ number: values[0], date: newDate });
  }, []);

  return (
    <InputGrid className='demo-input-grid'>
      <Label id={labelId} as='div'>
        Choose a start date
      </Label>
      <Slider
        thumbProps={() => ({
          'aria-labelledby': labelId,
          'aria-valuetext': dateFormatter.format(currentValue.date),
        })}
        values={[currentValue.number]}
        min={1}
        max={365}
        minLabel={'Date'}
        maxLabel={''}
        tooltipProps={() => {
          return { visible: false };
        }}
        onUpdate={updateValue}
        onChange={updateValue}
      />
      <Text variant='body' className='demo-text'>
        {dateFormatter.format(currentValue.date)}
      </Text>
    </InputGrid>
  );
};

Tooltips can also be customized such as changing the placement or the information that is displayed within it.

import * as React from 'react';
import { Slider, Label, InputGrid } from '@itwin/itwinui-react';

export default () => {
  const labelId = React.useId();

  return (
    <InputGrid className='demo-input-grid'>
      <Label id={labelId} as='div'>
        Choose a value
      </Label>
      <Slider
        thumbProps={() => ({ 'aria-labelledby': labelId })}
        values={[50]}
        min={0}
        max={100}
        tickLabels={['0', '20', '40', '60', '80', '100']}
        tooltipProps={(index, val) => {
          return { placement: 'right', content: `\$${val}.00` };
        }}
      />
    </InputGrid>
  );
};

Props

Prop	Description	Default
min	Minimum slider value. number	0
max	Maximum slider value. number	100
values	Array of one or more values to show. number[]
trackDisplayMode	Determines which segments are shown with color. 'none' - no colored tracks are displayed. 'auto' - segment display is based on number of values. 'odd-segments'- colored tracks shown in segments 1,3,5, etc. `Default if number of thumbs values are even.` 'even-segments'- colored tracks shown in segments 0,2,4, etc. `Default if number of thumbs values are odd.` TrackDisplayMode	'auto'
step	Step increment controls what values are allowed and the amount the value will change when left and right arrows are pressed when a Thumb has focus. number	1
disabled	Forces control to be displayed in a disabled state where no interactive value changes are allowed. boolean	false
tooltipProps	Function that can return tooltip props including content. (index: number, val: number, step: number) => Partial<Omit<Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ...; }, "as" \| ... 3 more ... \| keyof TooltipOptions> & { ...; } & PortalProps & TooltipOptions & { ...; }, "children">>
tickLabels	Either an array of labels that will be placed under auto generated tick marks that are spaced evenly across width of Slider or a custom component that allows custom content to be placed in tick mark area below slider. ReactNode
minLabel	Label for the minimum value. If undefined then the min value is shown. Use empty string for no label. ReactNode
maxLabel	Label for the maximum value. If undefined then the max value is shown. Use empty string for no label. ReactNode
trackContainerProps	Additional props for container `<div>` that hold the slider thumbs, and tracks. HTMLAttributes<HTMLDivElement>
minProps	Allows props to be passed for slider-min DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>
maxProps	Allows props to be passed for slider-max DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>
trackProps	Allows props to be passed for slider-track DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>
tickProps	Allows props to be passed for slider-tick DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>
ticksProps	Allows props to be passed for slider-ticks DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>
thumbMode	Defines the allowed behavior when moving Thumbs when multiple Thumbs are shown. It controls if a Thumb movement should be limited to only move in the segments adjacent to the Thumb. Possible values: 'allow-crossing' - allows thumb to cross other thumbs. Default. 'inhibit-crossing'- keeps the thumb from crossing and separated by a step. "allow-crossing" \| "inhibit-crossing"	'inhibit-crossing'
thumbProps	Callback that can provide additional props for `<div>` representing a thumb. (index: number) => Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ...; }
onChange	Callback fired at the end of a thumb move (i.e. on pointerUp) and when user clicks on rail. (values: readonly number[]) => void
onUpdate	Callback fired when the value(s) of the slider are internally updated during operations like dragging a Thumb. Use this callback with caution as a high-volume of updates will occur when dragging. (values: readonly number[]) => void
orientation	The orientation of slider "horizontal" \| "vertical"	'horizontal'
as	"symbol" \| "object" \| "div" \| "a" \| "abbr" \| "address" \| "area" \| "article" \| "aside" \| "audio" \| "b" \| "base" \| "bdi" \| "bdo" \| "big" \| "blockquote" \| "body" \| "br" \| "button" \| "canvas" \| ... 158 more ... \| FunctionComponent<...>