Theme

Pro installation quickstart 🚀

Introduction

The slider input is an advanced and highly configurable version of the native HTML range input. Some notable additions compared to the standard range input are:

  • Support for multi-value inputs.
  • Display tooltips to show selected values.
  • Show linked inputs for min and max values.
  • Render tick marks for value steps.
  • Add arbitrary tick marks.
  • Force selection to snap to tick marks.
  • Render bar chart data linked to selection values.

Slider Overview

7 mins

Basic example

Load live example

Native props

if you're familar with using the native HTML range input you'll find than many of the existing props you're familiar with work as expected with the slider input.

Load live example

Keyboard modifier keys

Even in its simplest form the slider input has a few tricks up its sleeve. Just like the native range input you can use your arrow keys to adjust the input value when it is focused — but with the slider input you can hold the shift key to increment by 10x and your system's modifer key (command or ctrl) to jump to the min / max values.

Keyboard number entry

Whenever you have a handle focused on a slider input you can type a value on your keyboard and after a slight debounce your slider handle will be set to the value you provided — or the closest available match.

Multi-value

To render two value handles on a slider input supply an array as the input's value. Control handles can be dragged through each other and your resulting array value will always be returned sorted in order from smallest to largest.

Load live example

Customizing handles

Using the maxHandleInner (default) and minHandleInner slots you can customize the appearance of your slider handles. The maxHandleInner slot is used for single-value slider inputs.

Load live example

Customizing tooltips

Tooltip visibility

By default slider tooltips show on hover and when a selection handle is being dragged. You can force tooltips into an on or off state by using the tooltip prop and providing a boolean value.

Load live example

Tooltip formating

By providing a function to the tooltip-format prop you can customize the value of your slider tooltip. Your tooltip-format function will be provided two arguments:

value: The current value that would be displayed in the tooltip by default. handle: The current handle being affected by the funciton. Either min or max.

Load live example

By using the tooltip-format prop you can introduce variety to your slider inputs — especially when combined with FormKit's section-key class prop system.

Load live example

Linked number inputs

Sometimes a range-style input is more useful for users if they're also able to directly enter numeric values in linked fields. You can reveal number inputs that are bound to the values of the slider range handles by setting the show-input prop to true.

Load live example

Linked input attributes

The linked number inputs are FormKit inputs. You can apply props to them using the provided props:

  • input-attrs: will bind your provided object to both the min and max inputs.
  • min-input-attrs: Object to bind to the linked min input.
  • max-input-attrs: Object to bind to the linked max input.
Load live example

Marks

Basic usage

The slider input supports the rendering of marks on the input's track. By setting the marks property to true marks will be rendered at every steps interval.

Load live example

With labels

You can enable labels for your marks by setting the mark-labels prop to true.

Load live example

Custom marks

By supplying an array of objects to the marks prop instead of a boolean you can place arbirtary marks on the slider's track. Mark objects shold have the folloing properties:

  • at: The position (value) on the track where the mark should render.
  • label: The label to render for the mark if the mark-labels prop is enabled.
  • class: A string of classes to apply to the mark element.
  • labelClasses: A string of classes to apply to the mark label element.
Load live example

Snap to marks

When supplying custom marks you may want to force the selection to snap to the provided marks. This can be achieved with the snap-to-marks prop. When snap-to-marks is true keyboard events will jump to the next closest mark and entered values through keyboard or linked inputs will snap to the nearest available mark.

Load live example

Styling marks

You can apply custom classes to your marks and mark labels by using the class and labelClasses properties on your mark objects.

Load live example

Scaling slider values

By default the slider input scales values linearly across its entire range. However, you can use the provided scaling-function or intervals props to change this behavior.

Using functions

The scaling-function prop accepts 3 values:

  • The string linear — this is the default behavior
  • The string log which will apply a logarithmic scaling function to your slider
  • An object which consits of two functions named forward and reverse which will apply your own scaling logic.
Load live example

Using Intervals

The intervals prop accepts an array of object where each object defines an interval range on the slider. Each obect contains:

  • value: The point on the slider at which the interval begins
  • step: The step size that should be used within the interval

Your last interval will cover the range extending from your specified value to the max prop value on your slider. If your lowest interval does not begin at the minimum possible value of your slider then an interval covering the range from your min slider prop to your first interval will be created for you. Its step value will be the value of the step prop on your slider input.

It's important to note that the visual representation of intervals on a slider track is based on the total number of possible steps within a given interval and not the interval's raw numeric value.

Load live example

Chart

You can render a bar chart above the slider with arbitrary values by suppling an array to the chart prop. The chart array has a similar structure to the marks array. Each nested object should contain:

  • at: The position (value) on the track where the bar for the chart should render.
  • value: A numeric value that will be used to calculate the relative height of the bar in the chart.

The slider input will iterate over you chart array and determine the largest value contained in the array, and then divide all other values by that largest value to determine the relative heights for rendering the bars of the chart.

Load live example

By combining the provided props for the slider component you can create a robust input to cover a variety of usecases. Here is an example for a price-range slider.

Load live example

Props & Attributes

PropTypeDefaultDescription
chartarraynoneAn array of objects containing at and value keys. Renders a relative-height bar-chart above the slider track.
input-attrsobject{}Applies custom attributes to the nested linked FormKit inputs for both min and max values.
intervalsarraynoneAn array of interval values consisting of value and step used to define differing scaling for different sections of a slider track.
marksboolean || arrayfalseWhen true, renders marks on the track at every step value. When an Array of objects with at and label keys, renders a mark on the track at every object's at value.
mark-labelsbooleanfalseEnables rendering of labels belowe marks on track
maxnumber100The maximum possible value of the slider range.
max-input-attrsobject{}Applies custom attributes to the nested linked FormKit input for the max value.
minnumber0The minimum possible value of the slider range.
min-input-attrsobject{}Applies custom attributes to the nested linked FormKit input for the min value.
prefixstringnoneCharacters that will always appear at the beginning of the input.
scaling-functionstring || objectlinearDefines scaling behavior for values on the rendered slider track using either a preset value string or a set of custom functions.
show-inputbooleanfalseRenders FormKit type="number" input(s) that are linked to the slider's value(s)
snap-to-marksbooleanfalseWhen enabled, forces user selection to snap to marks
stepnumber1The minimum value at which the slider value can increment / decrement.
suffixstringnoneCharacters that will always appear at the end of the input.
tooltipbooleannoneWhen set with a boolean value, forces the display of the slider's handle tooltip(s).
tooltip-formatfunctionnoneA function that is provided the value and handle for each slider handle which should return a string.
Show Universal props
configObject{}Configuration options to provide to the input’s node and any descendent node of this input.
delayNumber20Number of milliseconds to debounce an input’s value before the commit hook is dispatched.
dirtyBehaviorstringtouchedDetermines how the "dirty" flag of this input is set. Can be set to touched or comparetouched (the default) is more performant, but will not detect when the form is once again matching its initial state.
errorsArray[]Array of strings to show as error messages on this field.
helpString''Text for help text associated with the input.
idStringinput_{n}The unique id of the input. Providing an id also allows the input’s node to be globally accessed.
ignoreBooleanfalsePrevents an input from being included in any parent (group, list, form etc). Useful when using inputs for UI instead of actual values.
indexNumberundefinedAllows an input to be inserted at the given index if the parent is a list. If the input’s value is undefined, it inherits the value from that index position. If it has a value it inserts it into the lists’s values at the given index.
labelString''Text for the label element associated with the input.
nameStringinput_{n}The name of the input as identified in the data object. This should be unique within a group of fields.
parentFormKitNodecontextualBy default the parent is a wrapping group, list or form — but this props allows explicit assignment of the parent node.
prefix-iconString''Specifies an icon to put in the prefixIcon section.
preservebooleanfalsePreserves the value of the input on a parent group, list, or form when the input unmounts.
preserve-errorsbooleanfalseBy default errors set on inputs using setErrors are automatically cleared on input, setting this prop to true maintains the error until it is explicitly cleared.
sections-schemaObject{}An object of section keys and schema partial values, where each schema partial is applied to the respective section.
suffix-iconString''Specifies an icon to put in the suffixIcon section.
typeStringtextThe type of input to render from the library.
validationString, Array[]The validation rules to be applied to the input.
validation-visibilityStringblurDetermines when to show an input's failing validation rules. Valid values are blur, dirty, and live.
validation-labelString{label prop}Determines what label to use in validation error messages, by default it uses the label prop if available, otherwise it uses the name prop.
validation-rulesObject{}Additional custom validation rules to make available to the validation prop.
valueAnyundefinedSeeds the initial value of an input and/or its children. Not reactive. Can seed entire groups (forms) and lists..

Sections

You can target a specific section of an input using that section's "key", allowing you to modify that section's classes, HTML (via :sections-schema, or content (via slots)). Read more about sections here.

View on a larger screen to see this section diagram.

Choose your price range
Select available locations by price
📊
...
You must provide a rating.
Section-keyDescription
chartA container for the chart bar elements.
chartBarAn individual bar for the chart element.
fillThe fill for the selected range on the slider input.
handleMaxThe maximum value selection handle. This is the default handle for single-value slider inputs.
handleMinThe minimum value selection handle.
handlesA container for the track selection handles
linkedValuesA wrapper for the linked inputs for the slider’s minimum and maximum values.
markAn individual mark on the track.
markLabelThe label for an individual mark on the track.
marksA container for all of the marks on the track
maxValueThe linked FormKit number input for the slider’s maximum value. If the slider only has a single value this is rendered as a direct descendant of the sliderInner section.
minValueThe linked FormKit number input for the slider’s minimum value.
sliderInnerThe interior div that contains the slider input content.
trackA wrapper that contains all of the track markup for the slider input.
trackInnerAn interior wrapper for styling purposes that contains all of the track markup excluding the chart.
trackWrapperA wrapper that contains all of the track markup excluding the chart.
tooltipMinThe tooltip for the minimum value selection handle
tooltipMaxThe tooltip for the maximum value selection handle
Show Universal section keys
outerThe outermost wrapping element.
wrapperA wrapper around the label and input.
labelThe label of the input.
prefixHas no output by default, but allows content directly before an input element.
prefixIconAn element for outputting an icon before the prefix section.
innerA wrapper around the actual input element.
suffixHas no output by default, but allows content directly after an input element.
suffixIconAn element for outputting an icon after the suffix section.
inputThe input element itself.
helpThe element containing help text.
messagesA wrapper around all the messages.
messageThe element (or many elements) containing a message — most often validation and error messages.

Accessibility

All FormKit inputs are designed with the following accessibility considerations in mind. Help us continually improve accessibility for all by filing accessibility issues here:

Semantic markupAria attributesKeyboard accessibleFocus indicatorsColor contrast with the provided themeAccessible labels, help text, and errors
Section KeyAttributeDefaultDescription
maxValuetabindex-1Prioritizes keyboard focus order by setting it to -1 when input is disabled.
minValuetabindex-1Prioritizes keyboard focus order by setting it to -1 when input is disabled.
handleMaxtabindex-1 or 0Prioritizes keyboard focus order by setting it to -1 when input is disabled and 0 when its not.
handleMintabindex-1 or 0Prioritizes keyboard focus order by setting it to -1 when input is disabled and 0 when its not.
Show Universal section key
labellabelforAssociates the label to an input element. Users can click on the label to focus the input or to toggle between states.
inputinputdisabledDisables an HTML element, preventing user interaction and signaling a non-interactive state.
aria-describedbyAssociates an element with a description, aiding screen readers.
aria-requiredAdds this attribute when validation is required.
iconiconforWhenever icon is defined as a label it links it to an input element.

Keyboard Interactions

Keyboard EventDescription
TabMoves the focus to the next focusable input on the page.
Shift + TabMoves the focus to the previous focusable input on the page.