A spinbutton is an input widget that restricts its value to a set or range of discrete values. It provides an accessible, keyboard-navigable interface for numerical input that maintains value constraints, supports internationalization through custom text labels, and emits events when values change.

The recommended way to install the Spinbutton component is through a package manager like npm or yarn:

# Using npm
npm install @19h47/spinbutton

# Using yarn
yarn add @19h47/spinbutton

You can also download the component directly from the GitHub repository at https://github.com/19h47/19h47-spinbutton and include the distributed files in your project.

The Spinbutton requires a specific HTML structure to function properly:

The spinbutton is a div element with the role of spinbutton. It contains two buttons for increasing and decreasing the value, and an input field for displaying the current value.

<div role="spinbutton" aria-valuemin="0" aria-valuemax="100" aria-valuenow="10">
	<button class="js-decrease" tabindex="-1" aria-label="decrease" type="button">-</button>

	<input type="text" />

	<button class="js-increase" tabindex="-1" aria-label="increase" type="button">+</button>

</div>

Here is a simple example of how to use the spinbutton.

import Spinbutton from '@19h47/spinbutton';

const $element = document.querySelector('[role="spinbutton"]');
const spinbutton = new Spinbutton($element);

spinbutton.init();

The Spinbutton component emits a Spinbutton.change event when the value changes:

Here is an example of how to use the Spinbutton.change event.

import Spinbutton from '@19h47/spinbutton';

const $element = document.querySelector('[role="spinbutton"]');
const spinbutton = new Spinbutton($element);

spinbutton.init();

spinbutton.addEventListener('Spinbutton.change', event => {
	console.log(event.detail.value); // Return the current activate value
});

The spinbutton accepts the following options. The options can be set as data attributes on the div element or passed as an object when creating the spinbutton instance.

Example with options:

import Spinbutton from '@19h47/spinbutton';
const $element = document.querySelector('[role="spinbutton"]');
const options = {
	text: {
		single: 'item',
		plural: 'items'
	},
	step: 5,
	delay: 100
};
const spinbutton = new Spinbutton($element, options);
spinbutton.init();

The spin buttons provide the following keyboard support described in the spinbutton design pattern.

The spinbutton uses the following ARIA roles, properties, and states. The aria-valuenow attribute is updated when the value changes. The aria-valuemin and aria-valuemax attributes are used to define the minimum and maximum values of the spinbutton.

You can customize the step size:

<div role="spinbutton" data-spinbutton-step="5" aria-valuemin="5" aria-valuemax="50" aria-valuenow="5">
    <!-- buttons and input -->
</div>

You can provide custom text for singular and plural forms:

<div role="spinbutton" data-spinbutton-text='{"single":"barrel","plural":"barrels"}' aria-valuemin="1" aria-valuemax="100" aria-valuenow="1">
    <!-- buttons and input -->
</div>

You can dynamically change the minimum, maximum, and current values:

// Set new minimum value
spinbutton.setMin(10);

// Set new maximum value
spinbutton.setMax(200);

// Set new value
spinbutton.setValue(50);

Spinbutton Pattern