useElevator

A React hook for smooth scrolling. Inspired by Elevator.js.

Installation

npm install use-elevator

or using yarn:

yarn add use-elevator

Features

• Smooth scrolling to the top of the page or a specified element
• Customizable animation duration
• Callback functions for scroll start and end
• TypeScript support

How It Works

The useElevator hook is designed to create a smooth, pleasant scrolling experience. Here's a detailed breakdown of how it works:

Core Animation

1. Animation Loop: The hook uses requestAnimationFrame to create a smooth animation loop that updates the scroll position on each frame.

2. Easing Function: Rather than linear scrolling, the hook uses a quadratic easing function (easeInOutQuad) that starts slow, accelerates in the middle, and decelerates at the end - mimicking a real elevator's movement.

3. Duration Calculation: If no duration is provided, the hook automatically calculates an appropriate duration based on the scroll distance - longer distances get proportionally longer durations (with a maximum cap).

DOM Handling

1. Target Element Resolution: When a target element ID is provided, the hook calculates its position by traversing the DOM, accounting for nested offset parents.

2. Vertical Padding: You can add padding to stop before the target element (useful for fixed headers).

3. Window Blur Handling: If the user switches tabs during animation, the hook gracefully jumps to the destination.

Performance Optimizations

1. Refs for State: The hook uses React refs to store animation state, avoiding unnecessary re-renders during the animation.

2. Dependency Optimization: useCallback dependencies are minimized to prevent function recreation.

3. Memory Management: All resources are properly cleaned up on unmount, including animation frames.

Safety Features

1. Error Handling: The hook contains comprehensive error handling around DOM operations.

2. Type Safety: Built with TypeScript, providing complete type definitions for all options and return values.

3. Restart Prevention: The hook prevents starting multiple elevator animations simultaneously.

Event Handling

1. Callbacks: The hook provides startCallback and endCallback options to execute custom code at the beginning and end of the animation.

2. State Management: The hook provides an isElevating state that components can use to update UI accordingly.

The combination of these features creates a delightful scrolling experience that stands out from typical "back to top" buttons, adding personality to your application while still being fully functional.

Architecture

The useElevator hook is designed with a modular architecture for maintainability and testability:

lib/
├── utils/
│   └── animation.ts     # Animation utility functions
├── types.ts             # TypeScript interfaces
├── useElevator.ts       # Main hook implementation
└── index.ts             # Public exports

Core Components:

1. Main Hook (useElevator.ts)

   • React hook that coordinates the scrolling animation
   • Manages state and lifecycle events
   • Handles user interactions

2. Animation Utilities (utils/animation.ts)

   • Provides easing functions for smooth scrolling
   • Calculates element positions and scroll distances
   • Determines optimal animation durations

3. Type Definitions (types.ts)

   • TypeScript interfaces for hook options and returns
   • Ensures type safety across the library

This modular approach allows for:

• Easy testing of individual components
• Clear separation of concerns
• Simplified maintenance and future enhancements

Basic Usage

import { useElevator } from "use-elevator";

function ScrollToTopButton() {
  const { startElevating, isElevating } = useElevator({
    duration: 2000,
  });

  return (
    <button onClick={startElevating} disabled={isElevating}>
      {isElevating ? "Going up..." : "Back to top"}
    </button>
  );
}

API Reference

Options

| Property | Type | Default | Description | | --------------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------- | | targetElement | string | undefined | The ID of the element to scroll to. If not provided, scrolls to the top of the page. | | duration | number | 0 (auto) | Duration of the scroll animation in milliseconds. If not provided, the duration is calculated based on scroll distance. | | verticalPadding | number | 0 | Padding from the target element to stop above it. | | startCallback | function | undefined | Function to call when scrolling starts. | | endCallback | function | undefined | Function to call when scrolling ends. |

Returns

| Property | Type | Description | | -------------- | -------- | ------------------------------------------------- | | startElevating | function | Function to trigger the scroll animation. | | isElevating | boolean | Whether the scroll animation is currently active. |

Examples

Scroll to Specific Element

const { startElevating } = useElevator({
  targetElement: "contact-section",
  verticalPadding: 20,
});

With Callbacks

const { startElevating } = useElevator({
  startCallback: () => console.log("Starting elevator ride"),
  endCallback: () => console.log("Arrived at destination"),
});

Advanced Usage

Multiple Elevator Instances

You can create multiple elevator instances with different configurations:

function App() {
  // Elevator to the top of the page
  const topElevator = useElevator({
    duration: 2000,
  });

  // Elevator to a specific section
  const sectionElevator = useElevator({
    targetElement: "contact-section",
    verticalPadding: 80,
  });

  return (
    <div>
      <button onClick={topElevator.startElevating}>Back to Top</button>

      <button onClick={sectionElevator.startElevating}>Jump to Contact</button>
    </div>
  );
}

License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT © Bilal Mansuri