{/* Copyright 2020 Adobe. All rights reserved. This file is licensed to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. */}

import {Layout} from '@react-spectrum/docs'; export default Layout;

import docs from 'docs:@react-spectrum/slider'; import {HeaderInfo, PropTable, PageDescription} from '@react-spectrum/docs'; import packageData from '@react-spectrum/slider/package.json';

jsx

import {Flex} from '@react-spectrum/layout';
import {Slider} from '@react-spectrum/slider';

category: Forms after_version: 3.0.0-alpha.0

Slider

<PageDescription>{docs.exports.Slider.description}</PageDescription>

Example

tsx

<Slider label="Cookies to buy" defaultValue={12} />

Value

Sliders are controlled with the value prop and uncontrolled with the defaultValue prop. This value must fall between the Slider's minimum and maximum values, which default to 0 and 100 respectively.

tsx

function Example() {
  let [value, setValue] = React.useState(25);
  return (
    <Flex gap="size-150" wrap>
      <Slider
        label="Cookies to buy (Uncontrolled)"
        defaultValue={25} />
      <Slider
        label="Cookies to buy (Controlled)"
        value={value}
        onChange={setValue} />
    </Flex>
  );
}

Alternatively, a different scale can be used by setting the minValue and maxValue props.

tsx

<Slider
  label="Cookies to buy"
  minValue={50}
  maxValue={150}
  defaultValue={100} />

The slider value can be formatted by using the formatOptions prop. formatOptions is compatible with the option parameter of Intl.NumberFormat and is applied based on the current locale.

tsx

<Slider
  label="Currency"
  formatOptions={{style: 'currency', currency: 'JPY'}}
  defaultValue={60} />

HTML forms

Slider supports the name prop for integration with HTML forms.

tsx

<Slider
  label="Opacity"
  defaultValue={50}
  name="opacity" />

Labeling

Value labels are shown above the Slider by default, but they can also be moved to the side or hidden as needed. The label text should be in sentence case.

tsx

<Flex direction="column" maxWidth="size-5000" gap="size-300">
  <Slider label="Cookies to buy" defaultValue={25} />
  <Slider label="Donuts to buy" labelPosition="side" defaultValue={25} />
  <Slider label="Pastries to buy" showValueLabel={false} defaultValue={25} />
</Flex>

By default, the value label is formatted as a plain number. This can be customized using the following props.

showValueLabel: Allows you to display or hide the value label.
formatOptions: Allows you to customize the format of the value.
getValueLabel: Allows you to provide a custom function to format the value label.

tsx

<Flex direction="column" maxWidth="size-3000" gap="size-300">
  <Slider
    label="Cookies to buy"
    showValueLabel={false}
    defaultValue={90} />
  <Slider
    label="Percent donus eaten"
    maxValue={1}
    step={0.001}
    formatOptions={{style: 'percent', minimumFractionDigits: 1}}
    defaultValue={0.891} />
  <Slider
    label="Donuts to buy"
    maxValue={60}
    getValueLabel={donuts => `${donuts} of 60 Donuts`} />
</Flex>

Accessibility

Depending on the visualization being used (i.e. depending on the showValueLabel prop), a label, aria-label, or aria-labelledby prop is required.

Internationalization

To internationalize a Slider, a localized string should be passed to the label prop, aria-label prop, or value of the associated aria-labelledby element.

For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the slider is automatically flipped. In addition, Slider automatically uses the current locale to format the value label.

Props

Visual options

Fill

View guidelines

tsx

<Flex direction="column" gap="size-300">
  <Slider label="Opacity" maxValue={1} formatOptions={{style: 'percent'}} defaultValue={0.9} step={0.01} isFilled />
  <Slider label="Exposure" minValue={-5} maxValue={5} defaultValue={1.83} formatOptions={{signDisplay: 'always'}} step={0.01} fillOffset={0} isFilled />
</Flex>

Gradient

View guidelines

tsx

<Slider label="Filter density" trackGradient={['white', 'rgba(177,141,32,1)']} defaultValue={.3} maxValue={1} step={0.01} formatOptions={{style: 'percent'}} isFilled  />

Contextual help

A ContextualHelp element may be placed next to the label to provide additional information or help about a Slider.

tsx

import {Content, ContextualHelp, Heading} from '@adobe/react-spectrum';

<Slider
  label="Exposure"
  minValue={-100}
  maxValue={100}
  defaultValue={0}
  formatOptions={{signDisplay: 'always'}}
  isFilled
  fillOffset={0}
  contextualHelp={
    <ContextualHelp>
      <Heading>What is exposure?</Heading>
      <Content>Exposure adjusts how bright the image is.</Content>
    </ContextualHelp>
  } />

Disabled

View guidelines

tsx

<Slider label="Cookies to share" defaultValue={25} isDisabled />

Testing

The Slider features a draggable handle that the user can interact with to change its value. Please see the following section in the testing docs for more information on how to simulate this action in your test suite.

Simulating move event

Please also refer to React Spectrum's test suite if you find that the above isn't sufficient when resolving issues in your own test cases.