README

bsTouchspin is a lightweight, flexible, and customizable jQuery plugin that provides an easy-to-use spinner interface for numeric inputs. It allows for smooth increment and decrement of numeric values through up and down buttons, while supporting custom configurations for appearance and behavior.

Features

• Increment and decrement buttons for numeric inputs.
• Customizable options:
  • Minimum and maximum values.
  • Step size (fixed or dynamic).
  • Input size (sm | lg).
  • Prefix and postfix spans.
  • Custom button styles, icons, and behavior.
• Built-in number formatting options:
  • Currency.
  • Percent.
  • Number.
• Locale support for number formatting.
• Customizable events and callbacks, such as onInit, onStart, and onStop.
• Utility methods for formatting and handling decimals.
• Responsiveness and accessibility.
• Support for dynamic and real-time changes.

Installation

Using a Content Delivery Network (CDN)

Include the following scripts and styles in your HTML file:

<script src="https://code.jquery.com/jquery-3.6.4.min.js"></script>
<script src="path/to/bs-touchspin.min.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons/font/bootstrap-icons.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.7/dist/css/bootstrap.min.css">

Local Installation

1. Download the bs-touchspin script file and its dependencies (e.g., Bootstrap CSS/JS, Bootstrap Icons).
2. Include them in your project.

Usage

Basic Initialization

The simplest use case involves turning a standard text input into a touchspin spinner:

<input id="spinner" type="text">
<script>
    $('#spinner').bsTouchspin();
</script>

Options and Configuration

The plugin supports a wide range of customization options, as listed below:

General Configuration

The following global configuration options allow fine-tuning of touchspin behavior:

Changing Global Configuration

You can change the global configuration dynamically at runtime by using the $.bsTouchspin.setConfig() method:

$.bsTouchspin.setConfig({
    minSpeed: 10,        // Set the minimum holding speed to 10ms
    startSpeed: 500,     // Start speed reduced to 500ms
    delay: 800,          // Delay before onStop callback to 800ms
    locale: 'de-DE'      // Use German locale for number formatting
});

This will update the behavior of all future bsTouchspin instances created after the configuration is set.

Instance-Specific Configuration

Pass configuration options during initialization:

$('#spinner').bsTouchspin({
    size: 'sm',
    step: 0.5,
    min: 10,
    max: 50,
    formatter: 'percent',
    onStart: function (value) {
        console.log('Started with value:', value);
    },
    onStop: function (value, diff) {
        console.log('Stopped with value:', value, 'diff to start: ', diff);
    }
});

Note:

If step, min, or max are set as HTML attributes on the <input>, those attribute values take precedence over plugin options during initialization.

Configuration Options

Below is the full list of default options for the bsTouchspin plugin:

Methods

val

The val method allows you to set the spinner's value programmatically.

Usage:

$('#example-spinner').bsTouchspin('val', value);

• value: The numeric value you want to set for the spinner.

Examples:

1. Set the value of the spinner:

$('#example-spinner').bsTouchspin('val', 42); // Sets the spinner's value to 42.

Notes:

• Validation: The provided value is validated against the configured min, max, and step properties. If the value exceeds the defined limits, it will be automatically adjusted:

$('#example-spinner').bsTouchspin({
    min: 0,
    max: 100
});

$('#example-spinner').bsTouchspin('val', 150); // The value will be set to 100 since it exceeds the `max`.

• The applied value respects any configured formatting via options like formatter (e.g., currency or percentage).
• Direct external value assignments like $input.val('1') or $input.prop('value', '1') are not automatically processed by the plugin UI lifecycle. To keep validation, formatting, button states, and width updates in sync, use $('#example-spinner').bsTouchspin('val', 1).
• For fixed precision independent from step size, set decimals explicitly. Example: step: 0.01 with decimals: 4 increments by 0.01 and displays values like 1.2300.

setPrefix

Updates the prefix text at runtime.

$('#example-spinner').bsTouchspin('setPrefix', '€');

setPostfix

Updates the postfix text at runtime.

$('#example-spinner').bsTouchspin('setPostfix', 'kg');

destroy

Removes plugin markup, event handlers, and plugin data from the input and restores original input attributes/state.

$('#example-spinner').bsTouchspin('destroy');

Events

The plugin emits the following events that can be listened to:

• init.bs.touchspin: Triggered on initialization.
• start.bs.touchspin: Triggered when the spinner interaction starts.
• stop.bs.touchspin: Triggered when the spinner interaction stops.

Example Usage:

$('#spinner').on('init.bs.touchspin', function (event, startValue) {
    console.log('Touchspin initialized:', startValue);
});

$('#spinner').on('stop.bs.touchspin', function (event, stopValue, diff) {
    console.log('Touchspin stopped. Final value:', stopValue, 'Difference:', diff);
});

Event payloads:

• init.bs.touchspin => (event, startValue)
• start.bs.touchspin => (event, startValue)
• stop.bs.touchspin => (event, stopValue, diff)

Global API

The plugin namespace also exposes global defaults/config helpers:

• $.bsTouchspin.setDefaults(options)
• $.bsTouchspin.getDefaults()
• $.bsTouchspin.setConfig(options)
• $.bsTouchspin.getConfig()

Example:

$.bsTouchspin.setDefaults({
    buttons: {
        up: {class: 'btn-primary'},
        down: {class: 'btn-primary'}
    }
});

Utility Functions

The plugin provides useful utility functions for working with numeric values:

formatNumber(number, decimalPlaces, locale)

Formats a number with the desired decimal places and locale.

const formatted = $.bsTouchspin.utils.formatNumber(1234.56, 2, 'de-DE');
console.log(formatted); // "1.234,56"

formatCurrency(value, decimals, locale, currency)

Formats a value as currency.

const currency = $.bsTouchspin.utils.formatCurrency(200, 2, 'en-US', 'USD');
console.log(currency); // "$200.00"

formatPercent(value, decimals, locale)

Formats a value as a percentage.

const percent = $.bsTouchspin.utils.formatPercent(0.45, 2, 'de-DE');
console.log(percent); // "45,00%"

Example Integration

<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.7/dist/css/bootstrap.min.css">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons/font/bootstrap-icons.css">
    <script src="https://code.jquery.com/jquery-3.6.4.min.js"></script>
    <script src="path/to/bs-touchspin.min.js"></script>
</head>
<body>
<div class="container">
    <label for="example-spinner">Example Spinner</label>
    <input id="example-spinner" type="text"/>
</div>

<script>
    $('#example-spinner').bsTouchspin({
        step: 1,
        min: 0,
        max: 100,
        formatter: 'currency'
    });
</script>
</body>
</html>

Contributing

Feel free to fork the repository, open issues, or submit pull requests to improve the plugin. Contributions, feedback, and suggestions are highly welcome!

License

Licensed under the MIT License.

Author

This plugin was developed to enhance user interactions with input fields and provide a modern interface for numeric controls in web applications.