SliderPro

FormKit Pro Quick Installation Guide 🚀

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

<FormKit  type="slider"  label="A very basic slider"  help="Out of the box I'm not much different than a range input."/>

A very basic slider

Out of the box I'm not much different than a range input.

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.

<FormKit  type="slider"  name="slider"  label="Multiple Values"  :value="[50, 350]"  min="0"  max="500"  help="I now render two control handles"/>

Multiple Values

I now render two control handles

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.

<template>  <FormKit    type="slider"    label="A slider with styled marks and a custom handle"    value="50"    handle-class="!w-auto !h-auto"  >    <template #handleMaxInner>      <div class="p-2">        <svg xmlns="http://www.w3.org/2000/svg" height="1em" style="display: block;" viewBox="0 0 512 512"><!--! Font Awesome Free 6.4.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2023 Fonticons, Inc. --><path d="M406.6 374.6l96-96c12.5-12.5 12.5-32.8 0-45.3l-96-96c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3L402.7 224l-293.5 0 41.4-41.4c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0l-96 96c-12.5 12.5-12.5 32.8 0 45.3l96 96c12.5 12.5 32.8 12.5 45.3 0s12.5-32.8 0-45.3L109.3 288l293.5 0-41.4 41.4c-12.5 12.5-12.5 32.8 0 45.3s32.8 12.5 45.3 0z"/></svg>      </div>    </template>  </FormKit></template>

A slider with styled marks and a custom handle

Customizing tooltips

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.

<FormKit  type="slider"  label="Default Tooltip Visibility"  value="25"  help="I show my tooltip on hover and drag"/><FormKit  type="slider"  label="Force Show Tooltip"  value="50"  tooltip="true"  help="I always show my tooltip"/><FormKit  type="slider"  label="Force Hide Tooltip"  value="75"  tooltip="false"  help="I never show my tooltip. I'm basically a native range input"/>

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.

<FormKit  type="slider"  label="Default Tooltip Visibility"  :value="[60, 100]"  :tooltip-format="    (value, handle) => {      return `${handle === 'min' ? 'Min' : 'Max'}: ${value}`    }  "  tooltip="true"  help="I apply custom formatting to my tooltips"/>

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.

<FormKit  type="slider"  label="About how large should the spacing be?"  help="This is a rough estimate."  :value="[25, 75]"  :tooltip-format="(value, handle) => (handle === 'min' ? '👉' : '👈')"  tooltip-class="large"/><FormKit  type="slider"  label="What do you think of FormKit?"  help="be honest."  value="80"  :tooltip-format="    (value) => {      if (value < 25) {        return '😡'      } else if (value < 50) {        return '😐'      } else if (value < 75) {        return '😀'      } else if (value < 100) {        return '😍'      } else if (value === 100) {        return '🦄'      }    }  "  tooltip="true"  :fill-class="emotionClass"  tooltip-class="large"/>

About how large should the spacing be?

This is a rough estimate.

👉
👈

What do you think of FormKit?

be honest.

😍

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.

<FormKit  type="slider"  value="33"  label="A single slider with a visible input"  help="I have a single linked input"  show-input/><FormKit  type="slider"  :value="[33, 66]"  label="A slider with multiple inputs"  show-input/>

A single slider with a visible input

I have a single linked input

A slider with multiple inputs

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.

<FormKit  type="slider"  max="1000"  :value="[300, 800]"  label="Linked input attrs"  show-input  :input-attrs="{    sectionsSchema: {      prefix: {        $el: 'span',        children: '&dollar;',      },    },  }"  :min-input-attrs="{    label: 'Minimum Price',  }"  :max-input-attrs="{    label: 'Maximum Price',  }"/>

Linked input attrs

Minimum Price

Maximum Price

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.

<FormKit  type="slider"  label="I show marks on my track"  help="By default, marks are rendered at every step interval."  value="50"  step="10"  marks/>

I show marks on my track

By default, marks are rendered at every step interval.

With labels

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

<FormKit  type="slider"  label="I show marks on my track with labels"  help="Labels can be enabled via prop."  value="50"  step="10"  marks  mark-labels/>

I show marks on my track with labels

Labels can be enabled via prop.

0102030405060708090100

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.

<FormKit  type="slider"  label="I render custom marks"  value="50"  :marks="[    { at: 0, label: '0°C' },    { at: 20, label: '20°C' },    { at: 37, label: '37°C' },    { at: 100, label: '100°C' },  ]"  mark-labels/>

I render custom marks

0°C20°C37°C100°C

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.

<FormKit  type="slider"  label="I render custom marks"  value="37"  :marks="[    { at: 0, label: '0°C' },    { at: 20, label: '20°C' },    { at: 37, label: '37°C' },    { at: 100, label: '100°C' },  ]"  mark-labels  snap-to-marks/>

I render custom marks

0°C20°C37°C100°C

Styling marks

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

const styledMarks = [  {    at: 0,    label: '0',    class: 'tiny',    labelClass: 'red',  },  {    at: 25,    label: '25',    class: 'small',    labelClass: 'orange',  },  {    at: 50,    label: '50',    class: 'normal',    labelClass: 'yellow',  },  {    at: 75,    label: '75',    class: 'large',    labelClass: 'blue-green',  },  {    at: 100,    label: '100',    class: 'xlarge',    labelClass: 'green',  },]

I have styled marks

0255075100

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.

scaling-functions

scaling-utils

<FormKit  v-model="scalingValue"  type="slider"  label="Scaling: Linear"  scaling-function="linear"  v-bind="sharedProps"/><FormKit  v-model="scalingValue"  type="slider"  label="Scaling: Logarithmic"  scaling-function="log"  v-bind="sharedProps"/><FormKit  v-model="scalingValue"  type="slider"  label="Scaling: Custom Quadratic"  :scaling-function="customQuad"  v-bind="sharedProps"/><FormKit  v-model="scalingValue"  type="slider"  label="Scaling: Custom Sine Wave"  :scaling-function="customSine"  v-bind="sharedProps"/>

export const customQuad = {  forward: (value, min, max) => {    return Math.sqrt(value / max) * max  },  reverse: (percentage, min, max) => {    return percentage ** 2 / max  },}export const customSine = {  forward: (value, min, max) => {    return max * (Math.asin(value / 50 - 1) / Math.PI + 0.5)  },  reverse: (percentage, min, max) => {    return 50 * (Math.sin((Math.PI * (percentage - max / 2)) / max) + 1)  },}

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.

<script setup>const intervals = [  { value: 0, step: 10 },  { value: 100, step: 50 },  { value: 800, step: 100 },]const marks = [  { at: 0, label: '0' },  { at: 100, label: '100' },  { at: 800, label: '800' },  { at: 3000, label: '3000' },]</script><template>  <FormKit    type="slider"    label="Scaling: Interval"    :value="100"    :intervals="intervals"    :marks="marks"    mark-labels    min="0"    max="3000"  /></template>

Scaling: Interval

01008003000

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.

<FormKit  type="slider"  label="I render a bar chart above my track"  value="30"  :chart="[    { at: 0, value: 10 },    { at: 10, value: 15 },    { at: 20, value: 20 },    { at: 30, value: 25 },    { at: 40, value: 30 },    { at: 50, value: 35 },    { at: 60, value: 30 },    { at: 70, value: 25 },    { at: 80, value: 15 },    { at: 90, value: 5 },  ]"/>

I render a bar chart above my track

Full-featured 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.

<FormKit  type="slider"  label="Choose your price range"  :value="[800, 1200]"  :tooltip-format="(v) => `&dollar;${v}`"  tooltip="true"  min="0"  max="2000"  show-input  step="25"  :input-attrs="{    floatingLabel: true,    prefixIcon: 'dollar',  }"  :min-input-attrs="{    label: 'Minimum',  }"  :max-input-attrs="{    label: 'Maximum',  }"  :marks="[    { at: 0, label: '$0' },    { at: 500, label: '$500' },    { at: 1000, label: '$1000' },    { at: 1500, label: '$1500' },    { at: 2000, label: '$2000' },  ]"  mark-labels  :chart="chartData"/>

Props & Attributes

Prop	Type	Default	Description
`chart`	`array`	`none`	An array of objects containing `at` and `value` keys. Renders a relative-height bar-chart above the slider track.
`input-attrs`	`object`	`{}`	Applies custom attributes to the nested linked FormKit inputs for both min and max values.
`intervals`	`array`	`none`	An array of interval values consisting of `value` and `step` used to define differing scaling for different sections of a slider track.
`marks`	`boolean \|\| array`	`false`	When `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-labels`	`boolean`	`false`	Enables rendering of labels belowe marks on track
`max`	`number`	`100`	The maximum possible value of the slider range.
`max-input-attrs`	`object`	`{}`	Applies custom attributes to the nested linked FormKit input for the max value.
`min`	`number`	`0`	The minimum possible value of the slider range.
`min-input-attrs`	`object`	`{}`	Applies custom attributes to the nested linked FormKit input for the min value.
`prefix`	`string`	`none`	Characters that will always appear at the beginning of the input.
`scaling-function`	`string \|\| object`	`linear`	Defines scaling behavior for values on the rendered slider track using either a preset value string or a set of custom functions.
`show-input`	`boolean`	`false`	Renders FormKit `type="number"` input(s) that are linked to the slider's value(s)
`snap-to-marks`	`boolean`	`false`	When enabled, forces user selection to snap to marks
`step`	`number`	`1`	The minimum value at which the slider value can increment / decrement.
`suffix`	`string`	`none`	Characters that will always appear at the end of the input.
`tooltip`	`boolean`	`none`	When set with a boolean value, forces the display of the slider's handle tooltip(s).
`tooltip-format`	`function`	`none`	A function that is provided the `value` and `handle` for each slider handle which should return a `string`.
Show Universal props
`config`	`Object`	`{}`	Configuration options to provide to the input’s node and any descendent node of this input.
`delay`	`Number`	`20`	Number of milliseconds to debounce an input’s value before the `commit` hook is dispatched.
`dirtyBehavior`	`string`	`touched`	Determines how the "dirty" flag of this input is set. Can be set to `touched` or `compare` — `touched` (the default) is more performant, but will not detect when the form is once again matching its initial state.
`errors`	`Array`	`[]`	Array of strings to show as error messages on this field.
`help`	`String`	`''`	Text for help text associated with the input.
`id`	`String`	`input_{n}`	The unique `id` of the input. Providing an `id` also allows the input’s node to be globally accessed.
`ignore`	`Boolean`	`false`	Prevents an input from being included in any parent (group, list, form etc). Useful when using inputs for UI instead of actual values.
`index`	`Number`	`undefined`	Allows 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.
`label`	`String`	`''`	Text for the `label` element associated with the input.
`name`	`String`	`input_{n}`	The name of the input as identified in the data object. This should be unique within a group of fields.
`parent`	`FormKitNode`	`contextual`	By default the parent is a wrapping group, list or form — but this props allows explicit assignment of the parent node.
`prefix-icon`	`String`	`''`	Specifies an icon to put in the `prefixIcon` section.
`preserve`	`Boolean`	`false`	Preserves the value of the input on a parent group, list, or form when the input unmounts.
`preserve-errors`	`Boolean`	`false`	By 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-schema`	`Object`	`{}`	An object of section keys and schema partial values, where each schema partial is applied to the respective section.
`suffix-icon`	`String`	`''`	Specifies an icon to put in the `suffixIcon` section.
`type`	`String`	`text`	The type of input to render from the library.
`validation`	`String, Array`	`[]`	The validation rules to be applied to the input.
`validation-visibility`	`String`	`blur`	Determines when to show an input's failing validation rules. Valid values are `blur`, `dirty`, and `live`.
`validation-label`	`String`	`{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-rules`	`Object`	`{}`	Additional custom validation rules to make available to the validation prop.
`value`	`Any`	`undefined`	Seeds the initial value of an input and/or its children. Not reactive. Can seed entire groups (forms) and lists..

Sections & slot data

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.

outer

wrapper

label

Choose your price range

help

Select available locations by price

sliderInner

prefixIcon

prefix

track

chart

chartBar

📊

trackWrapper

trackInner

fill

marks

mark

markLabel

handles

handleMin

tooltipMin

handleMinInner

⚪

handleMax

tooltipMax

handleMaxInner

⚪

suffix

suffixIcon

maxValue

linkedValues

minValue