Slider

The <Slider> is a form component that allows users to quickly select a value within a range. They should be used when the upper and lower bounds of the range are known and static. Sliders provide a visual indication of adjustable content, where the user can increase or decrease the value by moving the handle along a horizontal track.

Anatomy

Sliders consist of a track element showing the range of available values, one or more thumbs showing the current values, an output displaying the current values textually, and an optional label.

The thumbs can be dragged to allow a user to change their value. In addition, the track can be clicked to move the nearest thumb to that position.

Appearance

The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.

Usage

A slider is useful when selecting a value or range within a continuous or evenly spaced numeric scale feels more natural through direct manipulation than by entering values manually. It is well suited for inputs where the approximate position on a scale matters more than exact precision, such as setting volume, adjusting brightness, or filtering results within a price or date range. By making the scale visible and interactive, a slider allows users to quickly explore and adjust values while maintaining a clear sense of their relative position.

Ranges

Use the range feature of a slider when users need to select both a minimum and maximum value within the same scale, such as defining a price range, date span, or acceptable measurement limits. This approach works best when the range boundaries are equally important and the relationship between them is immediately clear in a single, continuous control.

When multiple thumbs are rendered, each thumb should have an aria-label, which is provided via the thumbLabels prop.

import { Slider } from '@marigold/components';export default () => (  <Slider    defaultValue={[10, 30]}    thumbLabels={['min', 'max']}    step={5}    label="Price range"    formatOptions={{ style: 'currency', currency: 'EUR' }}  />);

Scale and Granularity

Choose a scale that aligns with the way users think about the values they are adjusting. Always define a clear starting point and ending point (`), and select step intervals that feel natural within that range.

If the user needs to work with very large value spans or make fine-tuned adjustments, a slider is not the best choice. In those cases, prefer using a different input method such as a number field.

import { Slider } from '@marigold/components';export default () => (  <Slider label="Rating" step={1} minValue={1} maxValue={5} defaultValue={2} />);

Value formatting

Always format the slider value using an appropriate number format to improve clarity and ensure the displayed information is meaningful. This helps users immediately understand the context of what they are selecting, supports decision-making, and reduces potential confusion.

You can define the format using the formatOptions prop. It supports all options available through Intl.NumberFormat, and will automatically localize the number format based on the user's system settings.

import { Slider } from '@marigold/components';export default () => (  <Slider    label="Currency"    formatOptions={{ style: 'currency', currency: 'EUR' }}    defaultValue={60}  />);

Min and Max Values

Set meaningful and realistic minimum and maximum values that reflect the task the user is trying to complete. These boundaries help users stay within a useful range and avoid invalid input.

By default, the slider values reflect percentages between 0 and 100. A different scale can be used by using the minValue and maxValue props.

import { Slider } from '@marigold/components';export default () => (  <Slider    label="Budget"    formatOptions={{ style: 'currency', currency: 'EUR' }}    defaultValue={680}    minValue={100}    maxValue={5000}    step={100}  />);

Usage in Forms

The name attribute determines how the slider's value is submitted with the form. For a single-thumb slider, name accepts a string and will submit a single numeric value. For a two-thumb slider, name accepts a string tuple, allowing both the minimum and maximum values to be submitted as separate fields. This ensures that the form captures the full range selection without additional processing.

import type { FormEvent } from 'react';import { Button, Form, Slider, Stack } from '@marigold/components';export default () => {  const handleSubmit = (e: FormEvent) => {    e.preventDefault();    const formData = new FormData(e.target as HTMLFormElement);    alert(      `Age is selected from ${formData.get('start')} to ${formData.get('end')}.`    );  };  return (    <Form onSubmit={handleSubmit}>      <Stack space={8} alignX="left">        <Slider          label="Age Range"          defaultValue={[20, 50]}          maxValue={100}          step={10}          name={['start', 'end']}          width="1/2"        />        <Button variant="primary" type="submit">          Submit        </Button>      </Stack>    </Form>  );};

Props

Slider

Alternative components

There are alternative UI elements that can be used in place of sliders, depending on the specific use case and design goals. Some alternatives include:

• NumberField: Instead of using a slider, users can directly input the desired value into a numeric input field. This approach provides precise control and is particularly useful when users need to input specific or exact values.

• Combobox: Can be used to present a predefined set of options from which users can choose. This can be a suitable alternative when there is a limited range of choices or discrete values to select from.

Related