@carbon/react/es/components/Slider/Slider.d.ts

React components for the Carbon Design System

/**
 * Copyright IBM Corp. 2016, 2025
 *
 * This source code is licensed under the Apache-2.0 license found in the
 * LICENSE file in the root directory of this source tree.
 */
import React, { PureComponent, ReactNode, type ChangeEvent, type FocusEvent, type InputHTMLAttributes, type KeyboardEvent, type KeyboardEventHandler, type MouseEvent, type RefObject, type TouchEvent } from 'react';
import { TranslateWithId } from '../../types/common';
declare const translationIds: {
    readonly autoCorrectAnnouncement: "carbon.slider.auto-correct-announcement";
};
/**
 * Message ids that will be passed to translateWithId().
 */
type TranslationKey = (typeof translationIds)[keyof typeof translationIds];
declare enum HandlePosition {
    LOWER = "lower",
    UPPER = "upper"
}
type ExcludedAttributes = 'onChange' | 'onBlur';
export interface SliderProps extends Omit<InputHTMLAttributes<HTMLInputElement>, ExcludedAttributes>, TranslateWithId<TranslationKey, {
    correctedValue?: string;
}> {
    /**
     * The `ariaLabel` for the `<input>`.
     */
    ariaLabelInput?: string;
    /**
     * The `ariaLabel` for the upper bound `<input>` and handle when there are two handles.
     */
    unstable_ariaLabelInputUpper?: string;
    /**
     * The child nodes.
     */
    children?: ReactNode;
    /**
     * The CSS class name for the slider, set on the wrapping div.
     */
    className?: string;
    /**
     * `true` to disable this slider.
     */
    disabled?: boolean;
    /**
     * The callback to format the label associated with the minimum/maximum value and the value tooltip when hideTextInput is true.
     */
    formatLabel?: (value: number, label: string | undefined) => string;
    /**
     * `true` to hide the number input box.
     */
    hideTextInput?: boolean;
    /**
     * The ID of the `<input>`.
     */
    id?: string;
    /**
     * The `type` attribute of the `<input>`.
     */
    inputType?: string;
    /**
     * `Specify whether the Slider is currently invalid
     */
    invalid?: boolean;
    /**
     * Provide the text that is displayed when the Slider is in an invalid state
     */
    invalidText?: ReactNode;
    /**
     * The label for the slider.
     */
    labelText?: ReactNode;
    /**
     * Specify whether you want the underlying label to be visually hidden
     */
    hideLabel?: boolean;
    /**
     * @deprecated
     * `true` to use the light version.
     */
    light?: boolean;
    /**
     * The maximum value.
     */
    max: number;
    /**
     * The label associated with the maximum value.
     */
    maxLabel?: string;
    /**
     * The minimum value.
     */
    min: number;
    /**
     * The label associated with the minimum value.
     */
    minLabel?: string;
    /**
     * The `name` attribute of the `<input>`.
     */
    name?: string;
    /**
     * The `name` attribute of the upper bound `<input>` when there are two handles.
     */
    unstable_nameUpper?: string;
    /**
     * Provide an optional function to be called when the input element
     * loses focus
     */
    onBlur?: (data: {
        value: string;
        handlePosition: HandlePosition | undefined;
    }) => void;
    /**
     * The callback to get notified of change in value.
     */
    onChange?: (data: {
        value: SliderProps['value'];
        valueUpper: SliderProps['unstable_valueUpper'];
    }) => void;
    /**
     * Provide an optional function to be called when a key is pressed in the number input.
     */
    onInputKeyUp?: KeyboardEventHandler<HTMLInputElement>;
    /**
     * The callback to get notified of value on handle release.
     */
    onRelease?: (data: {
        value: SliderProps['value'];
        valueUpper: SliderProps['unstable_valueUpper'];
    }) => void;
    /**
     * Whether the slider should be read-only
     */
    readOnly?: boolean;
    /**
     * `true` to specify if the control is required.
     */
    required?: boolean;
    /**
     * A value determining how much the value should increase/decrease by moving the thumb by mouse. If a value other than 1 is provided and the input is *not* hidden, the new step requirement should be added to a visible label. Values outside the `step` increment will be considered invalid.
     */
    step?: number;
    /**
     * A value determining how much the value should increase/decrease by Shift+arrow keys,
     * which will be `(max - min) / stepMultiplier`.
     */
    stepMultiplier?: number;
    /**
     * The value of the slider. When there are two handles, value is the lower
     * bound.
     */
    value: number;
    /**
     * The upper bound when there are two handles.
     */
    unstable_valueUpper?: number;
    /**
     * Specify whether the control is currently in warning state
     */
    warn?: boolean;
    /**
     * Provide the text that is displayed when the control is in warning state
     */
    warnText?: ReactNode;
}
interface CalcLeftPercentProps {
    clientX?: number;
    value?: number;
    range?: number;
}
declare class Slider extends PureComponent<SliderProps> {
    static contextType: React.Context<any>;
    static translationIds: "carbon.slider.auto-correct-announcement"[];
    state: {
        value: number;
        valueUpper: number | undefined;
        left: number;
        leftUpper: number;
        needsOnRelease: boolean;
        isValid: boolean;
        isValidUpper: boolean;
        activeHandle: undefined;
        correctedValue: null;
        correctedPosition: null;
        isRtl: boolean;
    };
    thumbRef: RefObject<HTMLDivElement | null>;
    thumbRefUpper: RefObject<HTMLDivElement | null>;
    filledTrackRef: RefObject<HTMLDivElement | null>;
    element: HTMLDivElement | null;
    inputId: string;
    track: HTMLDivElement | null | undefined;
    constructor(props: any);
    /**
     * Sets up initial slider position and value in response to component mount.
     */
    componentDidMount(): void;
    /**
     * Handles firing of `onChange` and `onRelease` callbacks to parent in
     * response to state changes.
     *
     * @param {*} prevProps prevProps
     * @param {*} prevState The previous Slider state, used to see if callbacks
     * should be called.
     */
    componentDidUpdate(prevProps: any, prevState: any): void;
    /**
     * Rounds a given value to the nearest step defined by the slider's `step`
     * prop.
     *
     * @param value - The value to adjust to the nearest step. Defaults to `0`.
     * @returns The value rounded to the precision determined by the step.
     */
    nearestStepValue(value?: number): number;
    handleDrag: (event: Event) => void;
    /**
     * Sets up "drag" event handlers and calls `this.onDrag` in case dragging
     * started on somewhere other than the thumb without a corresponding "move"
     * event.
     */
    onDragStart: (evt: MouseEvent<HTMLDivElement> | TouchEvent<HTMLDivElement>) => void;
    /**
     * Removes "drag" and "drag stop" event handlers and calls sets the flag
     * indicating that the `onRelease` callback should be called.
     */
    onDragStop: () => void;
    /**
     * Handles a "drag" event by recalculating the value/thumb and setting state
     * accordingly.
     *
     * @param evt The event.
     * @param activeHandle The first drag event call, we may have an explicit
     * activeHandle value, which is to be used before state is used.
     */
    _onDrag: (evt: globalThis.MouseEvent | globalThis.TouchEvent, activeHandle?: HandlePosition) => void;
    /**
     * Throttles calls to `this._onDrag` by limiting events to being processed at
     * most once every `EVENT_THROTTLE` milliseconds.
     */
    onDrag: import("es-toolkit/compat").DebouncedFunc<(evt: globalThis.MouseEvent | globalThis.TouchEvent, activeHandle?: HandlePosition) => void>;
    /**
     * Handles a `keydown` event by recalculating the value/thumb and setting
     * state accordingly.
     */
    onKeyDown: (evt: KeyboardEvent<HTMLDivElement>) => void;
    /**
     * Provides the two-way binding for the input field of the Slider. It also
     * Handles a change to the input field by recalculating the value/thumb and
     * setting state accordingly.
     */
    onChange: (evt: ChangeEvent<HTMLInputElement>) => void;
    /**
     * Checks for validity of input value after clicking out of the input. It also
     * Handles state change to isValid state.
     */
    onBlur: (evt: FocusEvent<HTMLInputElement>) => void;
    onInputKeyDown: (evt: KeyboardEvent<HTMLInputElement>) => void;
    processNewInputValue: (input: HTMLInputElement) => void;
    calcLeftPercent: ({ clientX, value, range }: CalcLeftPercentProps) => number;
    /**
     * Calculates the discrete value (snapped to the nearest step) along
     * with the corresponding handle position percentage.
     */
    calcDiscreteValueAndPercent: ({ leftPercent, }: {
        /** The percentage representing the position on the track. */
        leftPercent: number;
    }) => {
        discreteValue: number;
        discretePercent: number;
    };
    /**
     * Calculates the slider's value and handle position based on either a
     * mouse/touch event or an explicit value.
     */
    calcValue: ({ clientX, value, useRawValue, }: {
        /** The x-coordinate from a mouse/touch event. */
        clientX?: number;
        /** Value to base the calculations on (if no `clientX`). */
        value?: number;
        /** Whether to bypass the stepping logic and use the raw value. */
        useRawValue?: boolean;
    }) => {
        value: number | undefined;
        left: number;
    };
    calcDistanceToHandle: (handle: HandlePosition, clientX: number) => number;
    /**
     * Calculates a new slider value based on the current value, a change delta,
     * and a step.
     *
     * @param currentValue - The starting value from which the slider is moving.
     * @param delta - The amount to adjust the current value by.
     * @param step - The step. Defaults to `1`.
     * @returns The new slider value, rounded to the same number of decimal places
     *          as the step.
     */
    calcValueForDelta: (currentValue: number, delta: number, step?: number) => number;
    /**
     * Sets state relevant to the given handle position.
     *
     * Guards against setting either lower or upper values beyond its counterpart.
     */
    setValueLeftForHandle: (handle: HandlePosition, { value: newValue, left: newLeft }: {
        value: number;
        left: number;
    }) => void;
    setValueForHandle: (handle: HandlePosition, value: number | string) => void;
    isValidValueForPosition: ({ handle, value: newValue, min, max, }: {
        handle: HandlePosition;
        value: number;
        min: number;
        max: number;
    }) => boolean;
    isValidValue: ({ value, min, max, }: {
        value: number;
        min: number;
        max: number;
    }) => boolean;
    getAdjustedValueForPosition: ({ handle, value: newValue, min, max, }: {
        handle: HandlePosition;
        value: number;
        min: number;
        max: number;
    }) => number;
    getAdjustedValue: ({ value, min, max, }: {
        value: number;
        min: number;
        max: number;
    }) => number;
    /**
     * Get the bounding rect for the requested handles' DOM element.
     *
     * If the bounding rect is not available, a new, empty DOMRect is returned.
     */
    getHandleBoundingRect: (handle: HandlePosition) => DOMRect;
    getClientXFromEvent(event: globalThis.MouseEvent | globalThis.TouchEvent): number | undefined;
    hasTwoHandles(): boolean;
    static getDerivedStateFromProps(props: SliderProps, state: Slider['state']): Partial<{
        value: number;
        valueUpper: number | undefined;
        left: number;
        leftUpper: number;
        needsOnRelease: boolean;
        isValid: boolean;
        isValidUpper: boolean;
        activeHandle: undefined;
        correctedValue: null;
        correctedPosition: null;
        isRtl: boolean;
    }> | null;
    render(): import("react/jsx-runtime").JSX.Element;
}
export default Slider;