## Overview [#overview] The `Slider` component provides an accessible way for users to select a value or range of values along a continuous or discrete scale. Built on Base UI primitives, it offers full keyboard navigation, touch support, and optional tooltip displays. ## Usage [#usage] ```tsx import { Slider, SliderThumb } from "@tilt-legal/cubitt-components/primitives"; ``` ```tsx ``` Using Cubitt's URL-state hooks, you can sync the slider value with the URL by providing a `paramName`. The URL only updates when you release the slider thumb, not while dragging, to avoid performance issues: ```tsx // Slider value synced with ?volume=50 // Range slider synced with URL: // Advanced options: console.log('Brightness:', value)} defaultValue={[75]} max={100} > ``` ## Examples [#examples] ### Default [#default] ```tsx import { Slider, SliderThumb } from "@tilt-legal/cubitt-components/primitives"; export default function Component() { return (
); } ``` ### Range Slider [#range-slider] Use two thumbs to select a range of values. ```tsx import { Slider, SliderThumb } from "@tilt-legal/cubitt-components/primitives"; export default function Component() { return (
); } ``` ### With Labels [#with-labels] Add labels to indicate the range or meaning of values. ```tsx import { Slider, SliderThumb, Label } from "@tilt-legal/cubitt-components/primitives"; export default function Component() { return (
); } ``` ### With Tooltip [#with-tooltip] Show the current value in a tooltip while dragging. ```tsx import { Slider, Label } from "@tilt-legal/cubitt-components/primitives"; export default function Component() { return (
); } ``` ### With Ticks [#with-ticks] Display tick marks to indicate discrete values or steps. ```tsx import { Slider, SliderThumb, Label } from "@tilt-legal/cubitt-components/primitives"; import { cn } from "@tilt-legal/cubitt-components/utilities"; export default function Component() { const max = 12; const skipInterval = 2; const ticks = [...Array(max + 1)].map((_, i) => i); return (
); } ``` ### Price Range with Inputs [#price-range-with-inputs] Combine sliders with number inputs for precise control. ```tsx "use client"; import { SliderThumb, Label, Input } from "@tilt-legal/cubitt-components/primitives"; import { useState, useId } from "react"; import { Slider } from "@tilt-legal/cubitt-components/primitives"; export default function Component() { const id = useId(); const [sliderValue, setSliderValue] = useState([200, 800]); const [minInput, setMinInput] = useState("200"); const [maxInput, setMaxInput] = useState("800"); const minValue = 80; const maxValue = 900; const handleSliderChange = (value: number | readonly number[]) => { const values = Array.isArray(value) ? value : [value]; setSliderValue(values); setMinInput(values[0].toString()); setMaxInput(values[1].toString()); }; const validateMinInput = () => { const numValue = parseFloat(minInput); if ( !isNaN(numValue) && numValue >= minValue && numValue <= sliderValue[1] ) { setSliderValue([numValue, sliderValue[1]]); } else { setMinInput(sliderValue[0].toString()); } }; const validateMaxInput = () => { const numValue = parseFloat(maxInput); if ( !isNaN(numValue) && numValue <= maxValue && numValue >= sliderValue[0] ) { setSliderValue([sliderValue[0], numValue]); } else { setMaxInput(sliderValue[1].toString()); } }; return (
setMinInput(e.target.value)} onBlur={validateMinInput} />
setMaxInput(e.target.value)} onBlur={validateMaxInput} />
); } ``` ### Rating Slider [#rating-slider] Create custom rating interfaces with emoji indicators. ```tsx "use client"; import { SliderThumb, Label } from "@tilt-legal/cubitt-components/primitives"; import { useState } from "react"; import { Slider } from "@tilt-legal/cubitt-components/primitives"; export default function Component() { const [value, setValue] = useState([3]); const labels = ["Awful", "Poor", "Okay", "Good", "Amazing"]; return (
{labels[value[0] - 1]}
😡 setValue(Array.isArray(newValue) ? newValue : [newValue]) } min={1} max={5} > 😍
); } ``` ### Climate Control [#climate-control] Complex example with multiple sliders and reset functionality. ```tsx "use client"; import { SliderThumb, Label, Input, Button, } from "@tilt-legal/cubitt-components/primitives"; import { useState, useRef } from "react"; import { Slider } from "@tilt-legal/cubitt-components/primitives"; import { Temperature, Droplet, Wind, ArrowRotateClockwise, } from "@tilt-legal/cubitt-icons/ui/outline"; function ClimateSlider({ minValue, maxValue, initialValue, defaultValue, label, unit, icon, onRegisterReset, }: { minValue: number; maxValue: number; initialValue: number[]; defaultValue: number[]; label: string; unit: string; icon: React.ReactNode; onRegisterReset: (resetFn: () => void) => void; }) { const [sliderValue, setSliderValue] = useState(initialValue); const [inputValue, setInputValue] = useState(initialValue[0].toString()); // Register reset function React.useEffect(() => { onRegisterReset(() => { setSliderValue(defaultValue); setInputValue(defaultValue[0].toString()); }); }, [onRegisterReset, defaultValue]); // Handle changes... return (
{icon}
{ const values = Array.isArray(value) ? value : [value]; setSliderValue(values); setInputValue(values[0].toString()); }} min={minValue} max={maxValue} step={0.5} > setInputValue(e.target.value)} />
); } export default function Component() { const resetFunctionsRef = useRef<(() => void)[]>([]); return (
} onRegisterReset={(fn) => (resetFunctionsRef.current[0] = fn)} /> {/* More sliders... */}
); } ``` ### Vertical Slider [#vertical-slider] Sliders can be oriented vertically for space-constrained layouts. ```tsx import { Slider } from "@tilt-legal/cubitt-components/primitives"; export default function Component() { return (
`Value: ${value}`} tooltipVariant="light" />
); } ``` ### Disabled [#disabled] ```tsx import { Slider, SliderThumb } from "@tilt-legal/cubitt-components/primitives"; export default function Component() { return (
); } ``` ### URL State [#url-state] Sync the slider with the URL using `paramName`. ```tsx import { Slider, Label } from "@tilt-legal/cubitt-components/primitives"; export default function Component() { return (
); } ``` ## API Reference [#api-reference] ### Slider [#slider] The root slider component with track and range indicator. | Prop | Type | Default | Description | | ---------------- | ------------------------------------- | -------------- | --------------------------------------- | | `defaultValue` | `number[]` | — | The default value when uncontrolled. | | `value` | `number[]` | — | The controlled value of the slider. | | `onValueChange` | `(value: number \| number[]) => void` | — | Callback fired when the value changes. | | `min` | `number` | `0` | The minimum value of the slider. | | `max` | `number` | `100` | The maximum value of the slider. | | `step` | `number` | `1` | The stepping interval. | | `orientation` | `"horizontal"` \| `"vertical"` | `"horizontal"` | The orientation of the slider. | | `disabled` | `boolean` | `false` | Whether the slider is disabled. | | `showTooltip` | `boolean` | `false` | Show tooltip with value while dragging. | | `tooltipContent` | `(value: number) => React.ReactNode` | — | Custom content for the tooltip. | | `tooltipVariant` | `"default"` \| `"light"` | `"default"` | The visual variant of the tooltip. | | `name` | `string` | — | The name for form submission. | | `className` | `string` | — | Additional CSS classes for the slider. | #### URL State Props [#url-state-props] When provided with a `paramName`, the slider will sync its value with URL parameters via TanStack Router search params. The URL updates only when you release the thumb, not while dragging. | Prop | Type | Default | Description | | --------------------- | --------------------------- | ------- | ---------------------------------------------------------------------------- | | `paramName` | `string` | — | URL parameter name for syncing state with URL. Enables URL state management. | | `onUrlValueChange` | `(value: number[]) => void` | — | Callback when URL parameter value changes. | | `paramClearOnDefault` | `boolean` | `true` | Remove URL param when value equals default. | | `paramThrottle` | `number` | — | Throttle URL updates in milliseconds. | | `paramDebounce` | `number` | — | Debounce URL updates in milliseconds. | ### SliderThumb [#sliderthumb] The draggable thumb control for the slider. | Prop | Type | Description | | ----------- | -------- | ------------------------------------- | | `className` | `string` | Additional CSS classes for the thumb. |