tessl/npm-nouislider

Lightweight JavaScript range slider with no dependencies

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Value Management

Name: tessl/npm-nouislider
Author: tessl

Methods for getting and setting slider values programmatically, with support for individual handle control and validation.

Capabilities

get()

Returns the current values of all slider handles.

/**
 * Get current slider values
 * @returns Single value for single-handle sliders, array for multi-handle sliders
 */
slider.noUiSlider.get(): string | string[];

Usage Examples:

// Single handle slider
const singleValue = singleSlider.noUiSlider.get();
console.log(singleValue); // "42.00"

// Multi-handle slider  
const rangeValues = rangeSlider.noUiSlider.get();
console.log(rangeValues); // ["20.00", "80.00"]

// With custom formatting
const formattedValues = currencySlider.noUiSlider.get();
console.log(formattedValues); // ["$1,200", "$3,400"]

set()

Sets values for all slider handles.

/**
 * Set slider values
 * @param values - Single value or array of values to set
 * @param fireSetEvent - Whether to fire 'set' event (default: true)
 * @param exactInput - Skip stepping validation (default: false)
 */
slider.noUiSlider.set(
    values: number | number[], 
    fireSetEvent?: boolean, 
    exactInput?: boolean
): void;

Usage Examples:

// Set single value
singleSlider.noUiSlider.set(75);

// Set multiple values
rangeSlider.noUiSlider.set([30, 70]);

// Set values without triggering events
rangeSlider.noUiSlider.set([40, 60], false);

// Set values with exact positioning (skip stepping)
rangeSlider.noUiSlider.set([33.33, 66.67], true, true);

// Partial updates using null
rangeSlider.noUiSlider.set([null, 90]);  // Only update second handle
rangeSlider.noUiSlider.set([10, null]);  // Only update first handle

setHandle()

Sets the value for a specific handle by index.

/**
 * Set value for a specific handle
 * @param handleNumber - Zero-based handle index
 * @param value - Value to set
 * @param fireSetEvent - Whether to fire 'set' event (default: undefined -> true)
 * @param exactInput - Skip stepping validation (default: false)
 * @throws Error if handleNumber is invalid
 */
slider.noUiSlider.setHandle(
    handleNumber: number, 
    value: number, 
    fireSetEvent?: boolean, 
    exactInput?: boolean
): void;

Usage Examples:

// Set first handle (index 0)
rangeSlider.noUiSlider.setHandle(0, 25);

// Set second handle (index 1)
rangeSlider.noUiSlider.setHandle(1, 75);

// Set without triggering events
rangeSlider.noUiSlider.setHandle(0, 30, false);

// Set with exact positioning
rangeSlider.noUiSlider.setHandle(1, 83.5, true, true);

// Error handling
try {
    rangeSlider.noUiSlider.setHandle(5, 50);  // Invalid handle index
} catch (error) {
    console.error(error.message); // "noUiSlider: invalid handle number, got: 5"
}

reset()

Resets the slider to its initial values.

/**
 * Reset slider to initial start values
 * @param fireSetEvent - Whether to fire 'set' event (default: undefined -> true)
 */
slider.noUiSlider.reset(fireSetEvent?: boolean): void;

Usage Examples:

// Reset to initial values
slider.noUiSlider.reset();

// Reset without triggering events
slider.noUiSlider.reset(false);

// Example: Reset button implementation
document.getElementById('reset-button').addEventListener('click', function() {
    slider.noUiSlider.reset();
});

steps()

Returns the available step increments and decrements for each handle.

/**
 * Get available step increments for each handle
 * @returns Array of [decrement, increment] tuples for each handle
 */
slider.noUiSlider.steps(): [number | null, number | null][];

Usage Examples:

// Get available steps for a dual-handle slider
const stepOptions = rangeSlider.noUiSlider.steps();
console.log(stepOptions); 
// [[10, 5], [15, null]]  // First handle can -10 or +5, second can +15 but not increment

// Use with stepping controls
const prevButton = document.getElementById('prev');
const nextButton = document.getElementById('next');

function updateStepButtons() {
    const steps = slider.noUiSlider.steps();
    const [decrement, increment] = steps[0]; // For first handle
    
    prevButton.disabled = decrement === null;
    nextButton.disabled = increment === null;
}

// Update button states on slider changes
slider.noUiSlider.on('update', updateStepButtons);

Value Formatting and Parsing

Format Option Integration

Values returned by get() are processed through the format.to() function if provided:

// Slider with currency formatting
noUiSlider.create(element, {
    start: [1000, 3000],
    range: { min: 0, max: 5000 },
    format: {
        to: function(value) {
            return '$' + Math.round(value).toLocaleString();
        },
        from: function(value) {
            return Number(value.replace(/[$,]/g, ''));
        }
    }
});

// get() returns formatted values
const values = element.noUiSlider.get();
console.log(values); // ["$1,000", "$3,000"]

Value Parsing for set()

Values passed to set() and setHandle() are processed through format.from() if they are strings:

// These are equivalent when using the currency formatter above:
slider.noUiSlider.set([1500, 2500]);        // Numbers
slider.noUiSlider.set(['$1,500', '$2,500']); // Formatted strings

Value Constraints and Validation

Stepping Behavior

By default, values are adjusted to conform to step settings:

// Slider with step: 10
noUiSlider.create(element, {
    start: 50,
    step: 10,
    range: { min: 0, max: 100 }
});

// Value will be adjusted to nearest step
element.noUiSlider.set(47);  // Actually sets to 50
element.noUiSlider.set(53);  // Actually sets to 50

// Use exactInput to bypass stepping
element.noUiSlider.set(47, true, true);  // Sets exactly to 47

Margin and Limit Constraints

Values are automatically adjusted to respect margin and limit settings:

// Slider with margin: 10
noUiSlider.create(element, {
    start: [30, 70],
    margin: 10,
    range: { min: 0, max: 100 }
});

// Margin prevents handles from getting too close
element.noUiSlider.set([45, 50]);  // Second handle moves to maintain margin
console.log(element.noUiSlider.get()); // ["45.00", "55.00"]

Padding Constraints

Padding prevents handles from getting too close to the edges:

// Slider with padding
noUiSlider.create(element, {
    start: [20, 80],
    padding: [10, 15],  // 10 units from start, 15 from end
    range: { min: 0, max: 100 }
});

// Values are constrained by padding
element.noUiSlider.set([5, 95]);
console.log(element.noUiSlider.get()); // ["10.00", "85.00"]

Null Values and Partial Updates

Use null in the values array to leave specific handles unchanged:

// Only update the first handle
slider.noUiSlider.set([25, null]);

// Only update the second handle  
slider.noUiSlider.set([null, 75]);

// No effect - all values are null
slider.noUiSlider.set([null, null]);

// Mixed updates
slider.noUiSlider.set([10, null, 90]);  // Three-handle slider

Event Integration

Automatic Event Firing

Value changes trigger events by default:

slider.noUiSlider.on('set', function(values, handle) {
    console.log('Value set on handle', handle, ':', values[handle]);
});

// This triggers the 'set' event
slider.noUiSlider.set([40, 60]);

// This does not trigger the 'set' event
slider.noUiSlider.set([40, 60], false);

Event Suppression

Suppress events during programmatic updates:

// Bulk updates without intermediate events
function setBulkValues(newValues) {
    slider.noUiSlider.set(newValues, false);  // No events
    
    // Manually fire update event after all changes
    slider.noUiSlider.get(); // Get current values
    // Trigger custom handling...
}

Error Handling

Common Errors

// Invalid handle number in setHandle()
try {
    slider.noUiSlider.setHandle(10, 50);
} catch (error) {
    console.error(error.message); 
    // "noUiSlider (14.7.0): invalid handle number, got: 10"
}

// Invalid values are ignored or adjusted
slider.noUiSlider.set([NaN, 50]);     // NaN ignored, 50 applied
slider.noUiSlider.set(['invalid']);   // String parsing fails, ignored
slider.noUiSlider.set([]);            // Empty array ignored

Value Validation

// Values outside range are clamped
slider.noUiSlider.set([-10, 150]);  // Clamped to [0, 100]

// Invalid formats with custom formatter
slider.noUiSlider.set(['$invalid', '$2,000']);  // First value ignored

Install with Tessl CLI