Slider

The Slider component allows users to select a value from a continuous or stepped range by dragging a thumb.

Installation

$ cbui-cli install @crossbuildui/slider

To get started, please make sure you have installed cbui-cli globally and authenticated your account. This will ensure you can access all the necessary features.

View documents

Import

index.tsx

import { Slider } from '@/crossbuildui/slider';
// import Icon from 'react-native-vector-icons/MaterialIcons'; // Or your preferred icon library for start/end content

Slider Component

Basic Usage

A simple slider with a default value and a label.

MyComponent.tsx

<Slider defaultValue={50} label="Volume" />

Sizes

Adjust slider track and thumb size with sm, md (default), or lg.

MyComponent.tsx

<View style={{gap: 24}}>
  <Slider defaultValue={30} size="sm" label="Small Slider" />
  <Slider defaultValue={50} size="md" label="Medium Slider (Default)" />
  <Slider defaultValue={70} size="lg" label="Large Slider" />
</View>

Colors

Set the thematic color of the slider's filled track and thumb using the color prop.

MyComponent.tsx

<View style={{gap: 16}}>
  <Slider defaultValue={25} color="primary" label="Primary" />
  <Slider defaultValue={40} color="secondary" label="Secondary" />
  <Slider defaultValue={55} color="success" label="Success" />
  <Slider defaultValue={70} color="warning" label="Warning" />
  <Slider defaultValue={85} color="danger" label="Danger" />
  <Slider defaultValue={50} color="foreground" label="Foreground" />
</View>

Radius

Control the border radius of the track and thumb with none, sm, md (default), lg, or full.

MyComponent.tsx

<View style={{gap: 16}}>
  <Slider defaultValue={50} radius="none" label="No Radius" />
  <Slider defaultValue={50} radius="sm" label="Small Radius" />
  <Slider defaultValue={50} radius="md" label="Medium Radius (Default)" />
  <Slider defaultValue={50} radius="lg" label="Large Radius" />
  <Slider defaultValue={50} radius="full" label="Full Radius" />
</View>

Orientation

Sliders can be horizontal (default) or vertical.

MyComponent.tsx

<View style={{flexDirection: 'row', gap: 40, alignItems: 'center', height: 250}}>
  <Slider defaultValue={60} label="Horizontal (Default)" />
  <Slider
    orientation="vertical"
    defaultValue={75}
    label="Vertical Slider"
    minValue={0}
    maxValue={100}
  />
</View>

Step, Min & Max Values

Define the range and increment of the slider using minValue, maxValue, and step.

MyComponent.tsx

<View style={{gap: 16}}>
  <Slider
    label="Temperature"
    defaultValue={20}
    minValue={0}
    maxValue={40}
    step={0.5}
    formatOptions={{ style: 'unit', unit: 'celsius' }}
  />
  <Slider
    label="Brightness"
    defaultValue={75}
    minValue={0}
    maxValue={100}
    step={5}
  />
</View>

Controlled and Uncontrolled

Manage slider state externally using value and onChange, or use defaultValue for an uncontrolled component. onChangeEnd fires when the gesture ends.

MyComponent.tsx

function ControlledSlider() {
  const [value, setValue] = React.useState(60);

  return (
    <View style={{gap: 8}}>
      <Slider
        label="Controlled Slider"
        value={value}
        onChange={setValue}
        minValue={0}
        maxValue={100}
      />
      <Text>Current Value: {value}</Text>
    </View>
  );
}

// Uncontrolled (uses defaultValue)
// <Slider label="Uncontrolled" defaultValue={30} />

Label and Value Display

Provide a label, control value visibility with hideValue, and format the displayed value with formatOptions.

MyComponent.tsx

<View style={{gap: 16}}>
  <Slider defaultValue={50} label="Slider with Label" />
  <Slider defaultValue={70} label="Hide Value" hideValue />
  <Slider
    defaultValue={25}
    label="Custom Format"
    formatOptions={{ style: 'currency', currency: 'USD' }}
  />
</View>

Show Steps

Display visual indicators for each step on the track by enabling showSteps.

MyComponent.tsx

<Slider
  defaultValue={50}
  label="Slider with Steps"
  minValue={0}
  maxValue={100}
  step={10}
  showSteps
/>

Marks

Provide an array of marks to display custom labels and indicators at specific values along the track.

MyComponent.tsx

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

<Slider
  label="Temperature with Marks"
  defaultValue={20}
  minValue={0}
  maxValue={100}
  marks={marks}
  step={1}
/>

Fill Offset

Use fillOffset to change the starting point of the filled portion of the track. Useful for sliders representing a range that doesn't start from the minimum value (e.g., a balance slider centered at 0).

MyComponent.tsx

<View style={{gap: 24}}>
  <Slider
    label="Balance (-50 to 50, fill from 0)"
    defaultValue={10}
    minValue={-50}
    maxValue={50}
    fillOffset={0}
    step={1}
  />
  <Slider
    label="Range (0 to 100, fill from 50)"
    defaultValue={75}
    minValue={0}
    maxValue={100}
    fillOffset={50}
  />
</View>

Start and End Content

Add decorative or informative elements like icons or text at the beginning and end of the slider using startContent and endContent.

MyComponent.tsx

<View style={{gap: 16}}>
  <Slider
    label="Volume"
    defaultValue={40}
    startContent={<Icon name="volume-mute" size={20} color="gray" />}
    endContent={<Icon name="volume-high" size={20} color="gray" />}
  />
  <Slider
    label="Rating"
    defaultValue={3}
    minValue={1}
    maxValue={5}
    step={1}
    startContent={<Text style={{fontSize: 12, color: 'gray'}}>Min</Text>}
    endContent={<Text style={{fontSize: 12, color: 'gray'}}>Max</Text>}
  />
</View>

Disabled State

Disable the slider interaction using the isDisabled prop.

MyComponent.tsx

<Slider
  defaultValue={50}
  label="Disabled Slider"
  isDisabled
/>

Thumb Customization

Customize the thumb's appearance and behavior with hideThumb, showOutline, and disableThumbScale.

MyComponent.tsx

<View style={{gap: 16}}>
  <Slider
    defaultValue={50}
    label="Hidden Thumb"
    hideThumb
  />
  <Slider
    defaultValue={60}
    label="Thumb with Outline"
    showOutline
  />
  <Slider
    defaultValue={70}
    label="Thumb Scale Animation Disabled"
    disableThumbScale
  />
</View>

Props Overview

PROP	TYPE	DEFAULT	DESCRIPTION
`label`	`ReactNode`	-	Label for the slider.
`size`	`SliderSize`	`'md'`	Size of the slider.
`color`	`SliderColor`	`'primary'`	Thematic color.
`radius`	`SliderRadius`	`'md'`	Border radius.
`step`	`number`	`1`	Increment value.
`value`	`number`	-	Controlled value.
`defaultValue`	`number`	`0`	Uncontrolled initial value.
`onChange`	`(val: number) => void`	-	Callback on value change.
`onChangeEnd`	`(val: number) => void`	-	Callback on gesture end.
`minValue`	`number`	`0`	Minimum value.
`maxValue`	`number`	`100`	Maximum value.
`orientation`	`SliderOrientation`	`'horizontal'`	Orientation.
`fillOffset`	`number`	`minValue`	Start point for the fill.
`showSteps`	`boolean`	`false`	Show step indicators.
`showTooltip`	`boolean`	`false`	Show tooltip on drag.
`marks`	`SliderMark[]`	-	Marks to display on the track.
`startContent`	`ReactNode`	-	Content at the start of the slider.
`endContent`	`ReactNode`	-	Content at the end of the slider.
`formatOptions`	`Intl.NumberFormatOptions`	-	Options for formatting the displayed value.
`tooltipProps`	`any`	-	Props for the tooltip (e.g., style).
`showOutline`	`boolean`	`false`	Show outline around thumb.
`hideValue`	`boolean`	`false`	Hide displayed value.
`hideThumb`	`boolean`	`false`	Hide the thumb.
`disableThumbScale`	`boolean`	`false`	Disable thumb scale animation.
`isDisabled`	`boolean`	`false`	Disable the slider.
`styles`	`SliderSlotsStyles`	-	Custom styles for slider slots.
`style`	`StyleProp<ViewStyle>`	-	Style for the base container.

Styling

Customize the Slider appearance using the style prop for the main wrapper or the styles prop for more granular control over internal slots:

style: Applied to the outermost container (View) of the entire slider component.
styles.base: Styles for the outermost container.
styles.label: Styles for the label text.
styles.sliderWrapper: Styles for the container of the track, thumb, and content.
styles.track: Styles for the slider track.
styles.filler: Styles for the filled part of the track.
styles.thumb: Styles for the draggable thumb.
styles.thumbOutline: Styles for the thumb's outline.
styles.step: Styles for step indicators.
styles.markLabel: Styles for mark labels.
styles.markIndicator: Styles for mark indicator lines.
styles.tooltip: Styles for the tooltip.
styles.tooltipText: Styles for text inside the tooltip.
styles.startContentWrapper: Styles for the start content container.
styles.endContentWrapper: Styles for the end content container.
styles.valueText: Styles for the displayed value text.

MyComponent.tsx

<Slider
  label="Custom Styled Slider"
  defaultValue={45}
  style={{ marginVertical: 20, padding: 10, backgroundColor: '#e6e6fa' }} // Styles the outermost 'base' container
  styles={{
    base: { borderWidth: 1, borderColor: 'purple' },
    label: { color: 'navy', fontWeight: 'bold', fontStyle: 'italic' },
    sliderWrapper: { marginTop: 15 },
    track: { backgroundColor: 'lightgray', height: 10 },
    filler: { backgroundColor: 'teal' },
    thumb: {
      width: 28,
      height: 28,
      borderRadius: 6, // Square-ish thumb
      backgroundColor: 'darkorange',
      borderWidth: 2,
      borderColor: 'maroon'
    },
    valueText: { color: 'green', fontSize: 16 },
    tooltip: { backgroundColor: 'black', borderRadius: 8 },
    tooltipText: { color: 'white', fontWeight: 'bold' }
  }}
  showTooltip
/>

Accessibility

The Slider component aims to be accessible:

The component is built using GestureDetector for touch interactions.
The label prop provides context for the slider.
When isDisabled, interactions are prevented and opacity is reduced.
Consider providing accessibilityLabel, accessibilityValue, and accessibilityHint props directly to the root View or via the style/styles.base if further customization is needed for screen readers, although these are not explicitly handled by the component itself. Standard React Native accessibility props can be applied to the root element.

Select Switch

Slider

Installation

Import

Slider Component

Basic Usage

Sizes

Colors

Radius

Orientation

Step, Min & Max Values

Controlled and Uncontrolled

Label and Value Display

Tooltip

Show Steps

Marks

Fill Offset

Start and End Content

Disabled State

Thumb Customization

Props Overview

Styling

Accessibility

Default Slider

Size & Color

Vertical