Range | Components

Range

Input a numeric value along a track using a handle.

UsageGuidelinesAPI

A Range input lets users pick a numeric value along a track using a handle.

Usage

ReactVanilla

<Range max={100} min={0} defaultValue={30} />

<Range max={100} min={0} defaultValue={30} />

<div>
  <input
    max="100"
    min="0"
    type="range"
    aria-label="range"
    class="swan-range"
    value="30"
  />
</div>

<div>
  <input
    max="100"
    min="0"
    type="range"
    aria-label="range"
    class="swan-range"
    value="30"
  />
</div>

"unfilled"

The unfilled option makes the Range not be filled in to the left of the thumb.

<Range max={100} min={0} defaultValue={30} unfilled />

<Range max={100} min={0} defaultValue={30} unfilled />

Skins

Different skins are available for the common use cases of hue, contrast, and saturation, respectively. These skins are always "unfilled" to the left of the thumb.

<>
  <label for="exampleHue">Hue:</label>
  <Range skin="hue" max={100} min={0} defaultValue={30} id="exampleHue" />
  <label for="exampleContrast">Contrast:</label>
  <Range
    skin="contrast"
    max={100}
    min={0}
    defaultValue={30}
    id="exampleContrast"
  />
  <label for="exampleSaturation">Saturation:</label>
  <Range
    skin="saturation"
    gradientEndColor="green"
    max={100}
    min={0}
    defaultValue={30}
    id="exampleSaturation"
  />
</>

<>
  <label for="exampleHue">Hue:</label>
  <Range skin="hue" max={100} min={0} defaultValue={30} id="exampleHue" />
  <label for="exampleContrast">Contrast:</label>
  <Range
    skin="contrast"
    max={100}
    min={0}
    defaultValue={30}
    id="exampleContrast"
  />
  <label for="exampleSaturation">Saturation:</label>
  <Range
    skin="saturation"
    gradientEndColor="green"
    max={100}
    min={0}
    defaultValue={30}
    id="exampleSaturation"
  />
</>

Note that the saturation skin requires a value of gradientEndColor for the fully-saturated color shown at the Range's right end.

Custom

The custom skin allows you to create a Range with a smooth gradient between two custom colors, which are specified using gradientStartColor and gradientEndColor. This skin is always "unfilled" to the left of the thumb.

<Range
  skin="custom"
  gradientStartColor="orange"
  gradientEndColor="purple"
  max={100}
  min={0}
  defaultValue={30}
/>

<Range
  skin="custom"
  gradientStartColor="orange"
  gradientEndColor="purple"
  max={100}
  min={0}
  defaultValue={30}
/>

Managing State in React

As is the case with most form elements, folks often want to "control" this component. Controlling a component means that you take ownership over its state rather than letting the browser manage the state for you. When you control component, you own the source of truth for the UI. This means that you don't need to query the DOM in order to determine the current value of the element. So, when it comes time to use the value of the element somewhere else (e.g. submitting the selection to a back-end service), you can trust your stored value.

If you'd like to control this component, you'll need store the currently-selected value somewhere (e.g. React state or a Redux store), and you'll need to provide a handler to update that value when the user interacts with the component.

e.g.

ReactVanilla

() => {
  const [value, setValue] = React.useState(10)
  return (
    <>
      <Range
        value={value}
        onChange={event => setValue(event.target.value)}
        min={0}
        max={100}
      />
      <div>{value}</div>
    </>
  )
}

() => {
  const [value, setValue] = React.useState(10)
  return (
    <>
      <Range
        value={value}
        onChange={event => setValue(event.target.value)}
        min={0}
        max={100}
      />
      <div>{value}</div>
    </>
  )
}

<div class="swan-p-5">
  <input
    min="0"
    max="100"
    type="range"
    aria-label="range"
    class="swan-range"
    value="10"
  />
  <div>10</div>
</div>

<div class="swan-p-5">
  <input
    min="0"
    max="100"
    type="range"
    aria-label="range"
    class="swan-range"
    value="10"
  />
  <div>10</div>
</div>

Best practices

Use value labels and tick marks when users need to know exact numeric settings.
When modifying a Range using themes, while you can adjust the track's border width and color, be aware that the browsers interpret the border width differently. Some browsers draw the border inside the track (thus making the rest of the track shorter as the border gets thicker), some draw it outside the track, and some don't draw it at all.
Edge does not support changes to Range via themes. These browsers will always get the default Vistaprint brand look for this component.

Implementation

Our Range component puts Vistaprint styling on top of the native range input, so you can use any of that HTML's element's properties, such as min, max, and step.
When modifying a Range using themes, be aware that you can't adjust the overall margin or padding of the component, because the browsers are remarkably inconsistent about which parts of the range input they allow CSS to change. You can, however, adjust the total height of the component using --swan-range-height, and if you make this number taller than the height of the thumb, you will get extra whitespace around the thumb and track.

Props

Range

This component is implemented using the <input /> as the root element. You can utilize the native attributes supported by <input /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.

See core props for additional props that can be applied to this component.

prop	type	required	description	default
skin	`"standard" \| "hue" \| "saturation" \| "contrast" \| "custom" \| null`	false	The visual style of the Range	standard
unfilled	`boolean \| null`	false	Should it be unfilled or not? (Note: some skins will always be unfilled.)	false
gradientStartColor	`string \| null`	false	When using a skin with a two-color gradient, the start color of the gradient	null
gradientEndColor	`string \| null`	false	When using a skin with a two-color gradient, the end color of the gradient. "saturation" Ranges also need to specify this value	null