svelte-number-spinner

A highly configurable number spinner component for Svelte. It's a simple input field with a number that can be controlled using the mouse or keyboard. Pressing Alt or Alt+Shift makes steps smaller or bigger. Clicking on the input field without dragging the mouse or pressing Enter or any other non-control key like -, 1, 2, 3, ... starts the normal input mode.

New since version 0.6.0

Mobile devices with touch are now also supported which needed some major rework. I had to remove the option to select between double click or simple click to start editing. Now, only simple click is possible.

Demo

Simple example using number spinners for choosing a color

Number spinner demo showing all options

Installation

npm install svelte-number-spinner

Usage

<script>
  import NumberSpinner from "svelte-number-spinner";

  let value = 50;
</script>

<NumberSpinner bind:value min=0 max=100 />

Props

| Prop | Type | Default | Description | |---------------|----------|--------------|-----------------------------------------------------| | value | Number | 0 | Input value | | min | Number | -1e12 | Minimum value | | max | Number | +1e12 | Maximum value | | step | Number | 1 | Step | | precision | Number | = step | Precision of value (should be a fraction of step) | | speed | Number | 1 | Speed of value change on mouse drag | | keyStep | Number | = step * 10 | Step for keyboard interaction | | keyStepSlow | Number | = step | Slow step for keyboard interaction | | keyStepFast | Number | = step * 100 | Fast step for keyboard interaction | | decimals | Number | 0 | Number of decimals | | format | Function | undefined | Function to format value | | parse | Function | undefined | Function to parse formatted string back to value | | horizontal | Boolean | true | Change value by dragging horizontally | | vertical | Boolean | false | Change value by dragging vertically | | circular | Boolean | false | Enable circular range (good for angles, hours, ...) | | cursor | String | undefined | Individual cursor | | class | String | undefined | Custom component class name | | mainStyle | String | undefined | Custom inline style for general appearance | | focusStyle | String | undefined | Custom inline style when focussed | | draggingStyle | String | undefined | Custom inline style when dragging | | editingStyle | String | undefined | Custom inline style when editing | | fastStyle | String | undefined | Custom inline style for fast mode | | slowStyle | String | undefined | Custom inline style for slow mode | | options | Object | {} | Set any of the above props through this object |

Prop options

If you have many number spinners that should have the same props you might want to use the options object. This sets all of the given props to the respective value.

The props in the options object are applied when mounting the component. So, changing the options later won't update the props of the number spinner. Plus, the props in the options object will not be modified by the number spinner component. So, value should typically not be part of the options.

Example:

<script>
  import NumberSpinner from "svelte-number-spinner";

  let value1 = 50;
  let value2 = 10;
  let options = {horizontal:false, vertical:true}
</script>

<NumberSpinner bind:value={value1} min=0 max=100 {options} />
<NumberSpinner bind:value={value2} min=-30 max=30 {options} />

Steps and speed

There are several props that give you control about how you can interact with the value of the number spinner.

By default, dragging the mouse 1 pixel will increase/decrease the value by step. This is usualy quite good. But if have small ranges compared to step (e.g. a range from 0 to 10 with step 1) it's a bit to sensitive to control. In this case set speed to a smaller number, e.g. 0.1.

With keyboard interaction pressing an arrow key increases/decreases the value by 10*step. In slow mode (holding down Alt) default is one step per key stroke and in fast mode (Alt + Shift) it's 100*step. You can change these steps with the props keyStep, keyStepSlow and keyStepFast.

Formatting numbers

Numbers are displayed as integer values by default. Internally they are handled with the given precision.

Use the prop decimals to display floating point numbers.

Advanced formatting using format and parse

With the number spinner component you can only control numbers. But you can format this number in any possible way giving a callback function for the prop format. In most cases you should also give a reverse function that parses the string and converts it back to the correct number. This is necessary because in edit mode people will probably enter the number as they see it.

In this example the value e.g. 100 is formatted to "$ 100" using the function addDollar(val) for formatting and removeDollar(str) for parsing it back to a simple number. In fact it returns a string but parseFloat() is done in the number spinner component so you don't have to bother about that.

<script>
  let value = 100;

  function addDollar(val) {
    return "$ " + val;
  }
  function removeDollar(str) {
    return str.replace("$", "").trim();
  }
</script>

<NumberSpinner bind:value={value} format={addDollar} parse={removeDollar}/>

Using format and parse to implement non-linear

I found that these two functions could also be used to implement non-linear ranges like exponential/logarithmic scales:

<NumberSpinner bind:value={value} step={0.01} 
  format={val => Math.pow(10, val).toFixed(1)} 
  parse={val => Math.log10(val)}
  />

Styling

Styling with custom class name

You can style the component by overriding the default styles by giving a custom class name. If you give your own class name all default styles are removed. So, best would be to take the default styles below, put it in your global css, rename the class and remove and change stuff.

It's recomended to keep the order for :focus and .fast/.slow selectors. Default styles are:

 .default {
    display: inline-block;
    box-sizing: border-box;
    font-variant-numeric: tabular-nums;
    background-color: white;
    color: black;
    width: 4em;
    height: 1.6em;
    margin: 0px;
    padding: 0.25em;
    border: 0.075em solid #0004;
    border-radius: 0.15em;
    text-align: right;
    vertical-align: baseline;
    cursor: ew-resize;
  }

  .default:focus {
    border: 0.075em solid #06f;
    outline: none; /* removes the standard focus border */
  }

  .default.fast {
    border-top-width: 0.15em;
    padding-top: 0.175em;
  }

  .default.slow {
    border-bottom-width: 0.15em;
    padding-bottom: 0.175em;
  }

  .default.dragging {
    border-color: #04c;
  }

  .default.editing {
    cursor: initial;
  }

Styling with props

If you want to replace just a few of the styles or add some more without removing the default style, it might be easier for you to use the props mainStyle, focusStyle, fastStyle, slowStyle, draggingStyle and editingStyle.

For each of them you can give a style string like "width:80px; padding-right:10px". In the example below only the font color for fast and slow mode are changed:

<script>
  import NumberSpinner from "svelte-number-spinner";
</script>

<NumberSpinner fastStyle="color:orange" slowStyle="color:purple" />

Events

| Event Name | Callback | Description | |------------|---------------------|-------------------------------------------------------------------------------------| | input | (ev) => {ev.detail} | Fires when value changes. ev.detail gives the actual value | | change | (ev) => {ev.detail} | Fires when value changes, won't fire while typing. ev.detail gives the actual value | | dragstart | (ev) => {} | Fires when dragging starts | | dragend | (ev) => {} | Fires when dragging ends | | editstart | (ev) => {} | Fires when edit mode is started | | editend | (ev) => {} | Fires when edit mode is ended | | focus | (ev) => {} | Fires when the number spinner gets the focus | | blur | (ev) => {} | Fires when the number spinner loses the focus | | keydown | (ev) => {} | Original keydown event | | keypress | (ev) => {} | Original keypress event | | keyup | (ev) => {} | Original keyup event |

<script>
  import NumberSpinner from "svelte-number-spinner";

  function handleInput(ev) {
    console.log("Value send by input event:", ev.detail);    
  }

  function handleChange(ev) {
    console.log("Value send by change event:", ev.detail);    
  }
</script>

<NumberSpinner on:input="handleInput" on:change="handleChange" />

In most cases you will probably use bind:value to react to changes of the value. This is more or less the same as listening to the change event. Use the input event if you need to get the changes while the user is typing.

Develop

npm run dev

This will build the component and start a livereload server for the example.