noUiSlider: Lightweight JavaScript Range Slider

Common errors

• TypeError: noUiSlider.create is not a function

  cause Attempting to call `create` on an `undefined` or incorrect import of `noUiSlider`, often due to a wrong import statement or attempting a default import where a namespace import is required.
  fix Ensure you are using `import * as noUiSlider from 'nouislider';` in ESM or `const noUiSlider = require('nouislider');` in CJS. Also verify the package is correctly installed.

• Slider appears, but is unstyled or broken visually (e.g., handles are not positioned correctly).

  cause The noUiSlider CSS stylesheet has not been imported or is not correctly loaded by the bundler.
  fix Add `import 'nouislider/dist/nouislider.css';` (or the minified version) to your application's entry point or the component where the slider is used.

• Argument of type '(...)' is not assignable to parameter of type 'Pips'.

  cause TypeScript type mismatch when providing options to `noUiSlider.create` or `set`, specifically for the `pips` or `range` options, indicating incorrect structure or missing properties.
  fix Refer to the noUiSlider documentation and the TypeScript definitions for the correct structure of options like `pips`, `range`, or `connect`. Ensure all required properties are present and correctly typed.

Warnings

• breaking Version 15.5.0 introduced a fix for compositing issues in Safari, which could potentially be a breaking change when using a custom stylesheet. Styles might need adjustment if relying on previous Safari rendering quirks.
  Fix: Review and test custom stylesheets on Safari after upgrading to 15.5.0 or newer. Adjust CSS rules if visual regressions occur due to changed compositing behavior.
• gotcha When using TypeScript, remember that `noUiSlider.create` returns an API object (type `API`). Ensure your imports and variable typings correctly reflect this for proper type inference and checking.
  Fix: Use `import * as noUiSlider from 'nouislider';` and ensure variables interacting with the slider are typed correctly, e.g., `const slider: API = noUiSlider.create(...)`.
• gotcha noUiSlider requires its CSS file to be imported for correct visual rendering. Forgetting to import the CSS will result in an unstyled, unusable slider element.
  Fix: Always include `import 'nouislider/dist/nouislider.css';` (or `.min.css`) in your application's entry point or relevant component file.
• deprecated Older versions of noUiSlider might have been imported using default imports, but modern versions, especially with ESM, explicitly export a namespace object. Default imports can lead to undefined errors.
  Fix: Switch to named or namespace imports (e.g., `import * as noUiSlider from 'nouislider';`) for ESM compatibility.

Install

• npm install nouislider npm
• yarn add nouislider yarn
• pnpm add nouislider pnpm

Imports

• noUiSlider
  wrong:

  import noUiSlider from 'nouislider';

  correct:

  import * as noUiSlider from 'nouislider';
  import 'nouislider/dist/nouislider.css';

  noUiSlider exports a namespace object in ESM. The CSS must be imported separately for styling. For TypeScript, import types directly or use the `* as` import.
• nouislider.min.css

  import 'nouislider/dist/nouislider.min.css';

  Include the minified CSS for production builds. The default `nouislider.css` is also available.
• nouislider

  const noUiSlider = require('nouislider');

  For CommonJS environments, `require` loads the module. This is typically used in Node.js or older build setups.
• nouislider type

  import type { noUiSliderOptions, API } from 'nouislider';

  TypeScript types for options and the returned API are available and recommended for type-safe usage.

Quickstart

This quickstart code demonstrates how to initialize a basic noUiSlider with two handles, connect the range, add tooltips and pips, and listen for update events. It also shows programmatic value setting.

import * as noUiSlider from 'nouislider';
import 'nouislider/dist/nouislider.css';

const sliderElement = document.createElement('div');
sliderElement.id = 'mySlider';
document.body.appendChild(sliderElement);

const slider = noUiSlider.create(sliderElement, {
  start: [20, 80],
  connect: true,
  range: {
    'min': 0,
    'max': 100
  },
  tooltips: true,
  pips: {
    mode: 'steps',
    stepped: true,
    density: 4
  }
});

slider.on('update', (values, handle) => {
  console.log(`Slider updated: Handle ${handle} value: ${values[handle]}`);
});

// Example of setting new values programmatically
setTimeout(() => {
  slider.set([30, 70]);
  console.log('Slider values set to [30, 70] after 2 seconds.');
}, 2000);