SPFx PropertyPaneSlider: Working with Numeric Values in the Property Pane

Introduction

The SharePoint Framework provides several native controls for configuring Web Parts. One of the most useful when working with numeric values is the PropertyPaneSlider.

protected onInit(): Promise<void> {

this.properties.maxItems ??= 10;

return super.onInit();

}

Maximum number of items
Image size
Font size
Zoom level
Opacity
Percentage values
Number of search results

In this article, we’ll build a simple Web Part where the user chooses the maximum number of items using a Slider.

What We Are Building

Our Web Part exposes a single numeric property.

maxItems: number;

The Property Pane will display a slider ranging from 1 to 20.

As the user moves the slider, the selected value is immediately displayed inside the Web Part.

Defining the Web Part Property

The configuration property is defined as:

			
export interface IPropertyPaneSliderWebPartProps {
    maxItems: number;
}

Unlike previous examples, this property is a number.

React Component Properties

The React component receives exactly the same property.

			
export interface IPropertyPaneSliderWpProps {
    maxItems: number;
}

Again, React has no knowledge of the Property Pane.

It simply receives a numeric value.

Passing the Property to React

Inside the Web Part’s render() method:

			
const element: React.ReactElement<IPropertyPaneSliderWpProps> =
React.createElement(
    PropertyPaneSliderWp,
    {
        maxItems: this.properties.maxItems
    }
);
ReactDom.render(element, this.domElement);

		

The bridge remains exactly the same as every previous example.

			
Property Pane
↓
this.properties.maxItems
↓
props.maxItems
↓
React Component

		

The only difference is that the property type is now number.

React Component

The React component simply displays the selected value.

			
import * as React from 'react';
import { IPropertyPaneSliderWpProps } from './IPropertyPaneSliderWpProps';
const PropertyPaneSliderWp: React.FC<IPropertyPaneSliderWpProps> = (props) => {
    return (
        <div>
            <h1>Property Pane Slider</h1>
            <p>
                Maximum Items:
                <strong>
                    {props.maxItems}
                </strong>
            </p>
        </div>
    );
};
export default PropertyPaneSliderWp;

		

As the slider moves, React automatically receives the new value.

Creating the Slider

The Property Pane configuration is:

			
PropertyPaneSlider('maxItems', {
    label: 'Maximum Items',
    min: 1,
    max: 20,
    step: 1,
    showValue: true
})

		

This introduces several new properties.

Understanding min

min: 1

Defines the smallest value the user can select.

Understanding max

max: 20

Defines the largest value available.

The slider cannot move beyond this limit.

Understanding step

step: 1

Defines how much the value changes each time the user moves the slider.

Example:

If we changed it to:

step: 5

The values would become:

This is useful when only specific intervals are allowed.

Understanding showValue

showValue: true

Displays the current numeric value beside the slider.

Without it, users would only see the slider position.

For most business applications, displaying the current value provides a much better user experience.

Setting a Default Value

When the Web Part is added to a page for the first time, the property may not exist yet.

To avoid an undefined value, initialize it inside onInit().

			
protected onInit(): Promise<void> {
    this.properties.maxItems ??= 10;
    return super.onInit();
}

This guarantees that the slider starts at 10 the first time the Web Part is added.

After that, SharePoint persists the selected value automatically.

Property Flow

Like every Property Pane control, the Slider follows the same architecture.

			
Slider
↓
maxItems
↓
this.properties.maxItems
↓
render()
↓
props.maxItems
↓
React Component

		

Once this pattern becomes familiar, every Property Pane control becomes easier to understand.

Why Use a Slider?

A Slider is ideal whenever users need to select a value within a known range.

Advantages include:

Prevents invalid values
Faster than typing
Better visual feedback
Easier on touch devices
More intuitive for numeric configuration

Common Scenarios

The PropertyPaneSlider is commonly used for:

Maximum number of results
Font size
Image width
Card height
Animation speed
Zoom percentage
Transparency
Opacity
Margin size
Column width

Any configuration involving a numeric range is a good candidate.

Slider vs TextField

PropertyPaneTextField	PropertyPaneSlider
User types a number	User drags a slider
Requires validation	Always returns a valid value
Can receive invalid input	Restricted to configured limits
Better for arbitrary values	Better for ranges

If users must enter any number, use a TextField.

If the value belongs to a known interval, prefer a Slider.

Real-Time Updates

One interesting characteristic of the Slider is that SPFx updates the Web Part while the user is moving the control.

As the slider changes:

the Web Part immediately re-renders.

This demonstrates the reactive nature of the SharePoint Framework Property Pane.

Conclusion

The PropertyPaneSlider is one of the most user-friendly native Property Pane controls available in SPFx.

It provides an intuitive way to configure numeric values while preventing invalid input.

Combined with properties such as min, max, step, and showValue, it offers an excellent experience for both developers and end users.

Understanding the Slider also introduces an important concept: not every Property Pane control works with strings or booleans. Some controls naturally work with numeric values, and the Slider is the perfect example.