use-elevator/dist/index.d.ts

A React hook for smooth scrolling that transforms boring scroll-to-top actions into playful elevator experiences with customizable settings

/**
 * Options for configuring the useElevator hook.
 */
interface UseElevatorOptions {
    /**
     * The ID of the element to scroll to. If not provided, scrolls to the top of the page.
     */
    targetElement?: string;
    /**
     * Duration of the scroll animation in milliseconds.
     * If not provided, the duration is calculated based on scroll distance.
     */
    duration?: number;
    /**
     * Padding from the target element to stop above it.
     * @default 0
     */
    verticalPadding?: number;
    /**
     * Callback function to execute when scrolling starts.
     */
    startCallback?: () => void;
    /**
     * Callback function to execute when scrolling ends.
     */
    endCallback?: () => void;
}
/**
 * Return value from the useElevator hook.
 */
interface UseElevatorResult {
    /**
     * Function to trigger the elevator scrolling effect.
     */
    startElevating: () => void;
    /**
     * Whether the elevator effect is currently active.
     */
    isElevating: boolean;
}

/**
 * A React hook that provides a smooth scrolling effect.
 * Inspired by elevator.js but reimagined as a React hook with TypeScript support.
 *
 * @param {UseElevatorOptions} options - Configuration options for the elevator effect
 * @returns {UseElevatorResult} Object containing the startElevating function and isElevating state
 *
 * @example
 * ```jsx
 * const { startElevating, isElevating } = useElevator({
 *   duration: 2000,
 *   targetElement: 'section-id'
 * });
 *
 * return (
 *   <button onClick={startElevating} disabled={isElevating}>
 *     {isElevating ? 'Going up...' : 'Back to top'}
 *   </button>
 * );
 * ```
 */
declare const useElevator: (options?: UseElevatorOptions) => UseElevatorResult;

/**
 * Easing function for smooth scrolling animation with quadratic acceleration and deceleration.
 *
 * @param {number} time - Current time position in the animation
 * @param {number} start - Starting value
 * @param {number} change - Change in value
 * @param {number} duration - Total duration of animation
 * @returns {number} The calculated position value for the current time
 */
declare const easeInOutQuad: (time: number, start: number, change: number, duration: number) => number;
/**
 * Calculates the scroll position to an element, accounting for its offset parents.
 *
 * @param {string} elementId - ID of the target element to scroll to
 * @param {number} padding - Vertical padding to apply from the element (default: 0)
 * @returns {number} The vertical scroll position in pixels
 */
declare const calculateElementScrollPosition: (elementId: string, padding?: number) => number;
/**
 * Calculates optimal animation duration based on scroll distance.
 *
 * @param {number} distance - Distance to scroll in pixels
 * @param {number} customDuration - Optional user-defined duration
 * @returns {number} The calculated duration in milliseconds
 */
declare const calculateScrollDuration: (distance: number, customDuration?: number) => number;

export { calculateElementScrollPosition, calculateScrollDuration, easeInOutQuad, useElevator };
export type { UseElevatorOptions, UseElevatorResult };