# React Native Slider

> A React Native slider that looks native everywhere: iOS's knob, Material 3's handle with a value bubble, or a browser's range input. Range sliders with two thumbs, steps, labelled marks, snapping to marks, icons, keyboard and screen-reader support. Zero native code.

# Slider

`Slider` picks a number by dragging along a track, drawn the platform's way:

- **iOS**: a thin track and a white knob with a soft shadow, like `UISlider`.
- **Material**: Material 3's thick track with a slim handle, a gap either side of it, stop dots at the ends and a value bubble while dragging.
- **Web**: a browser's range input, with a dot in the primary colour, a pointer cursor, and a halo around the thumb on hover and focus that grows while you press and drag.

Tap anywhere on the track to jump there, or drag. Pass `range` for two thumbs.

```tsx
import { Slider } from 'patine-ui';
```

```tsx live
import { useState } from 'react';
import { Text, View } from 'react-native';
import { Slider } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  const [volume, setVolume] = useState(40);
  return (
    <View style={{ gap: 8 }}>
      <Slider
        value={volume}
        onValueChange={setVolume}
        minimumIcon={<Icon name="volumeOff" size="sm" />}
        maximumIcon={<Icon name="volume" size="sm" />}
        accessibilityLabel="Volume"
      />
      <Text>Volume: {volume}</Text>
    </View>
  );
}
```

## Example: a price filter

A shop's filters: a range slider sets the lowest and highest price, the bubble shows the price while you drag, and the result count follows as you go.

```tsx live
import { useState } from 'react';
import { Box, Button, HStack, Slider, Text, VStack } from 'patine-ui';

const PRICES = [18, 24, 29, 35, 39, 45, 49, 59, 64, 79, 89, 95, 120, 149, 189, 240, 320, 450];

export default function Example() {
  const [range, setRange] = useState<[number, number]>([40, 200]);
  const count = PRICES.filter((p) => p >= range[0] && p <= range[1]).length;
  return (
    <Box border radius="lg" padding="lg" gap="md" style={{ width: '100%', maxWidth: 400 }}>
      <HStack justify="space-between">
        <Text weight="semibold">Price</Text>
        <Text color="textSecondary">
          €{range[0]} – €{range[1]}{range[1] === 500 ? '+' : ''}
        </Text>
      </HStack>
      <Slider
        range
        value={range}
        onValueChange={setRange}
        min={0}
        max={500}
        step={10}
        valueLabel="drag"
        formatValue={(v) => `€${v}`}
        thumbLabels={['Lowest price', 'Highest price']}
      />
      <VStack gap="xs">
        <Button>{count ? `Show ${count} products` : 'No products in this range'}</Button>
        <Button variant="ghost" onPress={() => setRange([0, 500])}>Reset</Button>
      </VStack>
    </Box>
  );
}
```

## `onValueChange` and `onValueChanging`

Like the wheels, the slider has two callbacks:

| Callback | When | Use it for |
| --- | --- | --- |
| `onValueChange` | Once, when the finger lifts on a new value, or on each arrow key or screen-reader step | Updating state, saving |
| `onValueChanging` | On **every step** while dragging | Haptics, live previews |

The thumb follows the finger on its own while dragging, so a controlled slider doesn't need `onValueChanging` to move. Use it to preview the value as it changes:

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { Slider } from 'patine-ui';

export default function Example() {
  const [size, setSize] = useState(24);
  const [preview, setPreview] = useState(24);
  return (
    <View style={{ gap: 16 }}>
      <View style={{ height: 64, alignItems: 'center', justifyContent: 'center' }}>
        <View style={{ width: preview, height: preview, borderRadius: preview / 2, backgroundColor: '#C8460D' }} />
      </View>
      <Slider
        min={8}
        max={64}
        value={size}
        onValueChanging={setPreview}
        onValueChange={(next) => {
          setSize(next);
          setPreview(next);
        }}
        accessibilityLabel="Dot size"
      />
    </View>
  );
}
```

## Ranges

`range` gives the slider two thumbs, and its value becomes `[start, end]`. A touch grabs the nearest thumb, and neither can pass the other. Screen readers call them **Minimum** and **Maximum**; translate them with `thumbLabels`.

```tsx live
import { useState } from 'react';
import { Text, View } from 'react-native';
import { Slider } from 'patine-ui';

export default function Example() {
  const [price, setPrice] = useState<[number, number]>([120, 480]);
  return (
    <View style={{ gap: 8 }}>
      <Text>
        ${price[0]} – ${price[1]}
      </Text>
      <Slider
        range
        min={0}
        max={600}
        step={10}
        value={price}
        onValueChange={setPrice}
        formatValue={(v) => `${v}`}
        accessibilityLabel="Price"
      />
    </View>
  );
}
```

## Steps and marks

`step` sets how far the value moves (default `1`); `0` lets it take any value. `showSteps` puts a dot on the track at each step, left out when they'd be too close to tell apart. The Material design marks the track's inactive ends with stop dots, as Material 3 does.

```tsx live
import { useState } from 'react';
import { Slider } from 'patine-ui';

export default function Example() {
  const [rating, setRating] = useState(3);
  return <Slider min={1} max={5} step={1} showSteps value={rating} onValueChange={setRating} accessibilityLabel="Rating" />;
}
```

## Marks with labels

`marks` puts dots on the track at the values you pick; give one a `label` to write it under the track. Labels inside the filled part of the track read stronger.

```tsx live
import { useState } from 'react';
import { Slider } from 'patine-ui';

const marks = [
  { value: 0, label: '0°C' },
  { value: 20, label: '20°C' },
  { value: 37, label: '37°C' },
  { value: 100, label: '100°C' },
];

export default function Example() {
  const [temperature, setTemperature] = useState(20);
  return <Slider marks={marks} value={temperature} onValueChange={setTemperature} accessibilityLabel="Temperature" />;
}
```

### Only the marks

`snapToMarks` restricts the value to the marks: a drag jumps to the nearest one, and arrow keys and screen readers step from mark to mark.

```tsx live
import { useState } from 'react';
import { Slider } from 'patine-ui';

const marks = [
  { value: 0, label: '0°C' },
  { value: 20, label: '20°C' },
  { value: 37, label: '37°C' },
  { value: 100, label: '100°C' },
];

export default function Example() {
  const [temperature, setTemperature] = useState(20);
  return (
    <Slider
      marks={marks}
      snapToMarks
      value={temperature}
      onValueChange={setTemperature}
      formatValue={(v) => `${v}°C`}
      accessibilityLabel="Temperature"
    />
  );
}
```

## Value bubble

`valueLabel` sets when a bubble shows the value over the thumb: `'drag'` while dragging (the Material design's default), `'always'`, or `'never'` (the default elsewhere). With `'always'` the slider keeps room above the track for it. `formatValue` sets the bubble's text, which screen readers read too.

```tsx live
import { useState } from 'react';
import { Slider } from 'patine-ui';

export default function Example() {
  const [opacity, setOpacity] = useState(0.8);
  return (
    <Slider
      min={0}
      max={1}
      step={0.05}
      valueLabel="always"
      formatValue={(v) => `${Math.round(v * 100)}%`}
      value={opacity}
      onValueChange={setOpacity}
      accessibilityLabel="Opacity"
    />
  );
}
```

## Keyboard and screen readers

Each thumb is an adjustable control: screen readers step it with swipe up and down (iOS) or the volume keys (Android), and read `formatValue`'s text. On the web, Tab focuses a thumb; arrow keys step it, Page Up and Page Down move a tenth of the range, and Home and End go to the ends.

The track's touch area is 44 pt tall however thin it looks, as iOS asks, and a sheet's swipe to close doesn't take over a drag on it.

## Right to left

In an RTL layout the track fills from the right, and dragging follows.

```tsx live
import { View } from 'react-native';
import { Slider, Text } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  return (
    <View style={{ direction: 'rtl', gap: 8 }}>
      <Text>בהירות</Text>
      <Slider defaultValue={65} minimumIcon={<Icon name="sun" size={14} />} maximumIcon={<Icon name="sun" size={22} />} accessibilityLabel="בהירות" />
    </View>
  );
}
```

## A price filter

A range slider with fields beside it, as shops do: dragging updates the numbers, and `onValueChanging` keeps them live while the thumb moves.

```tsx live
import { useState } from 'react';
import { Button, HStack, Slider, Text, VStack } from 'patine-ui';

const format = (v: number) => `${v}`;

export default function Example() {
  const [range, setRange] = useState<[number, number]>([40, 220]);
  const [live, setLive] = useState(range);
  return (
    <VStack gap="md" style={{ maxWidth: 380, width: '100%' }}>
      <HStack justify="space-between">
        <Text weight="semibold">Price</Text>
        <Text color="textSecondary">{format(live[0])} – {format(live[1])}{live[1] === 500 ? '+' : ''}</Text>
      </HStack>
      <Slider
        range
        min={0}
        max={500}
        step={10}
        value={range}
        onValueChanging={setLive}
        onValueChange={(v) => {
          setRange(v);
          setLive(v);
        }}
        formatValue={format}
        marks={[0, { value: 250, label: '$250' }, 500]}
        accessibilityLabel="Price"
      />
      <Button onPress={() => {}}>Show 128 results</Button>
    </VStack>
  );
}
```

## Designs

```tsx live
import { Slider, Text, VStack } from 'patine-ui';

const DESIGNS = { brand: 'Brand', ios: 'iOS', material: 'Material', web: 'Web' } as const;

export default function Example() {
  return (
    <VStack gap="md" style={{ maxWidth: 380, width: '100%' }}>
      {Object.entries(DESIGNS).map(([design, label]) => (
        <VStack key={design} gap="xs">
          <Text size="xs" color="textSecondary">{label}</Text>
          <Slider design={design as keyof typeof DESIGNS} defaultValue={40} step={10} showSteps accessibilityLabel={label} />
        </VStack>
      ))}
    </VStack>
  );
}
```

## Styling

`styles` takes these slots: `container`, `track` (every piece of the track), `activeTrack` (the filled part), `thumb`, `mark`, `markLabel`, `valueLabel` and `valueLabelText`. The filled track and Material's handle use the theme's `primary` colour.

```tsx
<Slider value={value} onValueChange={setValue} styles={{ activeTrack: { backgroundColor: '#34C759' }, thumb: { borderWidth: 1 } }} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number`, or `[number, number]` with `range` | — | Controlled value. |
| `defaultValue` | `number`, or `[number, number]` with `range` | `min`, or `[min, max]` | Uncontrolled starting value. |
| `onValueChange` | `(value) => void` | — | When the finger lifts on a new value, or on a key or screen-reader step. |
| `onValueChanging` | `(value) => void` | — | On every step while dragging. |
| `range` | `boolean` | `false` | Two thumbs; the value is `[start, end]`. |
| `min` | `number` | `0` | The lowest value. |
| `max` | `number` | `100` | The highest value. |
| `step` | `number` | `1` | The value moves in steps this big; `0` for any value. |
| `showSteps` | `boolean` | `false` | A dot on the track at each step. |
| `marks` | `(number \| { value, label? })[]` | — | Dots at these values, with labels under the track. |
| `snapToMarks` | `boolean` | `false` | Only the marks can be picked. |
| `valueLabel` | `'never' \| 'drag' \| 'always'` | `'drag'` in Material, else `'never'` | When a bubble shows the value over the thumb. |
| `formatValue` | `(value: number) => string` | the number, with the step's decimals | Text for the bubble and screen readers. |
| `minimumIcon` | `ReactNode` | — | Before the track, like a quiet speaker beside a volume slider. |
| `maximumIcon` | `ReactNode` | — | After the track. |
| `disabled` | `boolean` | `false` | Dims the slider and ignores touches and keys. |
| `accessibilityLabel` | `string` | — | What screen readers call the slider. |
| `thumbLabels` | `[string, string]` | `['Minimum', 'Maximum']` | With `range`, what screen readers call each thumb. |
| `design` | `'brand' \| 'ios' \| 'material' \| 'web' \| 'native'` | from `PatineProvider` | The look to follow, over the provider's: [brand, iOS, Material or web](../guides/designs), or `'native'` for the platform's own. |
| `theme` | `DeepPartial<Theme>` | — | Theme override. |
| `style` / `styles` | `StyleProp<ViewStyle>` / `SlotStyles<SliderSlot>` | — | The root, and the [slots above](#styling). |
| `testID` | `string` | — | On the root; the track gets `${testID}-track`, the thumbs `${testID}-thumb-0` and `-1`. |

## Related

- [Rating](./rating): a score in stars
- [Haptics guide](../guides/haptics): a tick on each step with `onValueChanging`
- [Accessibility guide](../guides/accessibility)
