@19h47/spinbutton

@19h47/spinbutton

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.

Installation

Using Package Manager

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

Manual Download

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.

DOM structure

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>

JavaScript

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();

Event Handling

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

Event	Args	Description
Spinbutton.change	value	Return the current activate value

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
});

Configuration Options

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.

Option	Type		Default	Attributes
text	object	Object containing single and plural text.	-	data-spinbutton-text
step	number	The step value to increase or decrease the value.	1	data-spinbutton-step
delay	number	The delay in milliseconds before the event is triggered.	20	data-spinbutton-delay

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();

Keyboard Support

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

Key	Function
Down Arrow	Decreases value 1 (or step option if given) step.
Up Arrow	Increases the value 1 (or step option if given) step.
Page Down	Decreases the value 5 (or step option multiply by 5 if given) steps.
Page Up	Increases the value 5 (or step option multiply by 5 if given) steps.
Home	Decreases to mimimum value (if given).
End	Increases to maximum value (if given).

Role, Property, State, and Tabindex Attributes

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.

Role	Attribute	Element	Usage
spinbutton		div	Identifies the div element as a spinbutton.
spinbutton	aria-valuemin	div	The minimum value of the spinbutton.
spinbutton	aria-valuemax	div	The maximum value of the spinbutton.
spinbutton	aria-valuenow	div	The current value of the spinbutton.
spinbutton	aria-valuetext	div	The text representation of the current value.

Customization Examples

Step Size

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>

Custom Text

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>

Dynamic Control

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);

References

Spinbutton Pattern