PHPackages                             webcito/bs-touchspin - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. webcito/bs-touchspin

ActiveLibrary[Utility & Helpers](/categories/utility)

webcito/bs-touchspin
====================

A jQuery touchspin input plugin requiring Bootstrap 5.

1.0.4(11mo ago)1211MIT

Since Jun 18Pushed 11mo ago1 watchersCompare

[ Source](https://github.com/ThomasDev-de/bs-touchspin)[ Packagist](https://packagist.org/packages/webcito/bs-touchspin)[ RSS](/packages/webcito-bs-touchspin/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (7)Dependencies (4)Versions (8)Used By (0)

bsTouchspin Plugin
==================

[](#bstouchspin-plugin)

`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.

[![img.png](demo/img.png)](demo/img.png)
----------------------------------------

[](#)

Features
--------

[](#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
------------

[](#installation)

### Using a Content Delivery Network (CDN)

[](#using-a-content-delivery-network-cdn)

Include the following scripts and styles in your HTML file:

```

```

### Local Installation

[](#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
-----

[](#usage)

### Basic Initialization

[](#basic-initialization)

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

```

    $('#spinner').bsTouchspin();

```

---

Options and Configuration
-------------------------

[](#options-and-configuration)

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

### General Configuration

[](#general-configuration)

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

OptionDescriptionData TypeDefault`minSpeed`The minimum speed (in ms) for holding the increment or decrement button.`number``1``startSpeed`The initial speed (in ms) when holding the increment or decrement button.`number``600``delay`Delay (in ms) before triggering the stop callback after releasing a button or leaving focus.`number``1000``locale`Defines the locale used for number formatting (e.g., `'en-US'`, `'de-DE'`, etc.).`string``'en-US'``maximumMax`The value that is taken for max if max has not been defined.`number|null``2.147.483.647``maximumMin`The value that is taken for min if min is not defined.`number|null``-2.147.483.648``inputMinWidth`A minimum width for the input field and formatting output. It can have all CSS values for width.`number``75`---

#### Changing Global Configuration

[](#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

[](#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:

[](#note)

If configurable values such as **`min`**, **`max`**, **`step`**, or other numeric settings are already defined as **HTML attributes** on the `` element (e.g., `min="10"`, `max="50"`), the HTML attributes will typically **take precedence over JavaScript configurations** unless explicitly overridden by the JavaScript options provided during initialization.

---

### Configuration Options

[](#configuration-options)

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

OptionDescriptionData TypeDefault`size`Sets the size of the input. Acceptable values: `null`, `sm`, or `lg`.`string` or `null``null``step`Defines the step size for increments or decrements. Set to `"any"` for dynamic step size.`number` or `string``"any"``min`The minimum value allowed for the input.`number` or `null``null``max`The maximum value allowed for the input.`number` or `null``null``prefix`Prefix text or symbol shown before the input value.`string` or `null``null``postfix`Postfix text or symbol shown after the input value.`string` or `null``null``allowInput`Allows manual input of a value in the input field.`boolean``true``buttons.up.class`CSS classes for the increment ("up") button.`string``'btn-secondary rounded-end-pill fw-bold'``buttons.up.icon`Icon for the increment ("up") button (uses Bootstrap Icons).`string``'bi bi-plus-lg'``buttons.up.iconSetZero`Icon for the increment button when the value reaches zero.`string``'bi bi-trash'``buttons.down.class`CSS classes for the decrement ("down") button.`string``'btn-secondary rounded-start-pill fw-bold'``buttons.down.icon`Icon for the decrement ("down") button (uses Bootstrap Icons).`string``'bi bi-dash-lg'``buttons.down.iconSetZero`Icon for the decrement button when the value reaches zero.`string``'bi bi-trash'``formatter`Formatting style for the input value. Acceptable values: `'number'`, `'currency'`, or `'percent'`. You can also specify your own formatting function. The parameters `value`, `decimals` and `locale` are passed into the case.`string` or `function``'number'``onInit`Callback function, executed during initialization.`function``function (value) {}``onStart`Callback function, executed when incrementing or decrementing starts.`function``function (value) {}``onStop`Callback function, executed when incrementing or decrementing stops.`function``function (value, diff) {}`---

Methods
-------

[](#methods)

### `val`

[](#val)

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

#### **Usage:**

[](#usage-1)

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

- **`value`**: The numeric value you want to set for the spinner.

#### **Examples:**

[](#examples)

1. **Set the value of the spinner:**

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

#### **Notes:**

[](#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).

Events
------

[](#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:

[](#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);
});
```

---

Utility Functions
-----------------

[](#utility-functions)

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

### `formatNumber(number, decimalPlaces, locale)`

[](#formatnumbernumber-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)`

[](#formatcurrencyvalue-decimals-locale)

Formats a value as currency.

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

### `formatPercent(value, decimals, locale)`

[](#formatpercentvalue-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
-------------------

[](#example-integration)

```
>

    Example Spinner

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

```

---

Contributing
------------

[](#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
-------

[](#license)

Licensed under the MIT License.

---

### Author

[](#author)

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

```

```

###  Health Score

29

—

LowBetter than 59% of packages

Maintenance52

Moderate activity, may be stable

Popularity9

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

7

Last Release

333d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/6d5f10c16b4b6bd1ac531ffc39c23c569490ec4630829511692c03ec89d36a11?d=identicon)[thomasK81](/maintainers/thomasK81)

---

Top Contributors

[![ThomasDev-de](https://avatars.githubusercontent.com/u/67106837?v=4)](https://github.com/ThomasDev-de "ThomasDev-de (12 commits)")

---

Tags

uijquerywidgetbootstrapinputspinnerbootstrap5Bootstrap Iconstouchspinnumber-input

### Embed Badge

![Health badge](/badges/webcito-bs-touchspin/health.svg)

```
[![Health](https://phpackages.com/badges/webcito-bs-touchspin/health.svg)](https://phpackages.com/packages/webcito-bs-touchspin)
```

###  Alternatives

[kartik-v/yii2-widget-touchspin

A Yii2 wrapper widget for the Bootstrap Switch plugin to use checkboxes & radios as toggle touchspines (sub repo split from yii2-widgets)

184.1M6](/packages/kartik-v-yii2-widget-touchspin)[kartik-v/yii2-editable

An enhanced editable widget for Yii 2.0 that allows easy editing of displayed data with numerous configuration possibilities.

1163.2M59](/packages/kartik-v-yii2-editable)[kartik-v/yii2-widget-rating

A Yii2 widget for the simple yet powerful bootstrap-star-rating plugin with fractional rating support (sub repo split from yii2-widgets)

444.1M8](/packages/kartik-v-yii2-widget-rating)[kartik-v/yii2-widget-switchinput

A Yii2 wrapper widget for the Bootstrap Switch plugin to use checkboxes & radios as toggle switchinputes (sub repo split from yii2-widgets)

384.4M13](/packages/kartik-v-yii2-widget-switchinput)[techlab/smartwizard

The awesome jQuery step wizard plugin

79096.2k2](/packages/techlab-smartwizard)[kartik-v/yii2-sortable-input

Sortable input widget based on yii2-sortable extension.

24660.4k2](/packages/kartik-v-yii2-sortable-input)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)