Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

use-pull-to-refresh

Senbonzakura123418.8kMIT2.4.1TypeScript support: included

A simple React custom hook for pull-to-refresh function that support NextJs

react, typescript, ssr, nextjs, custom-hook

readme

Use Pull To Refresh npm

npm bundle size License is maintained

Table of contents

Description

A simple React custom hook for pull-to-refresh function that support NextJs SSR.

Purposes

Lots of web application needs custom scroll area for various reasons, however since we are not using browser native scroll, the native pull to refresh API is unusable since it's tied to the scroll event on html tag. This hooks is the solution to resolve this issue by recreating the native pull top behavior while also let you choose what proccess to run on each pull event end.

Prerequisites

This project requires NodeJS (version 16 or later) and React 17+

Getting Started

This custom hook helps you implement the pull-to-refresh feature in your app. It supports NextJs SSR that some other packages don't. It also allows support of a custom Scroll Area that was created by yourself.

What's the different to other similar packages?

Installation

BEFORE YOU INSTALL: please read the prerequisites

To install and set up the library, run:

$ npm i use-pull-to-refresh

Or if you prefer using Yarn:

$ yarn add use-pull-to-refresh

Or if you prefer using pnpm:

$ pnpm add use-pull-to-refresh

Usage

NextJs Example With TailwindCSS

import { useRouter } from 'next/router';
import { usePullToRefresh } from 'use-pull-to-refresh';

const MAXIMUM_PULL_LENGTH = 240;
const REFRESH_THRESHOLD = 180;

export default function PageRefresh() {
    const { isReady, reload } = useRouter();

    const { isRefreshing, pullPosition } = usePullToRefresh({
        // you can choose what behavior for `onRefresh`, could be calling an API to load more data, or refresh whole page.
        onRefresh: reload,
        maximumPullLength: MAXIMUM_PULL_LENGTH,
        refreshThreshold: REFRESH_THRESHOLD,
        isDisabled: !isReady
    });

    return (
        <div
            style={{
                top: (isRefreshing ? REFRESH_THRESHOLD : pullPosition) / 3,
                opacity: isRefreshing || pullPosition > 0 ? 1 : 0
            }}
            className='bg-base-100 fixed inset-x-1/2 z-30 h-8 w-8 -translate-x-1/2 rounded-full p-2 shadow'
        >
            <div
                className={`h-full w-full ${isRefreshing ? 'animate-spin' : ''}`}
                style={!isRefreshing ? { transform: `rotate(${pullPosition}deg)` } : {}}
            >
                <AnySpinnerSVGIconComponentWorksHere className='h-full w-full' />
            </div>
        </div>
    );
}

API

Parameters

type UsePullToRefreshParams = {
    onRefresh: () => void;
    maximumPullLength?: number;
    refreshThreshold?: number;
    isDisabled?: boolean;
};
  • onRefresh (required): refresh callback function run when pull event end.
  • maximumPullLength: limit how far the refresh icon was pulled down.
  • refreshThreshold: pullPosition that will trigger onRefresh function.
  • isDisabled: disabling pull function in case the onRefresh function is not ready to run.

Return Type

type UsePullToRefreshReturn = {
    isRefreshing: boolean;
    pullPosition: number;
};
  • isRefreshing: indicate refresh callback function is running.
  • pullPosition: current pull gesture position.

Change Log

Authors

License

MIT License © Senbonzakura1234

changelog

use-pull-to-refresh

2.4.1

Patch Changes

  • 4ec1ba9: Update packages version, change recommened extentions list.

2.4.0

Minor Changes

  • 660933d: Migrate from pnpm to npm

2.3.3

Patch Changes

  • a2a8cfd: Update dev dependencies version, update Readme document.

2.3.2

Patch Changes

  • 36aaf47: Update react peer dep

2.3.1

Patch Changes

  • 6433c20: Use AbortController to cancel events, Remove dependency because setState callbacks are stable, Update CI

2.3.0

Minor Changes

  • 771d6b5: Change dependencies of react package. Refactor code.

2.2.1

Patch Changes

  • 4319d5a: Refactor code
  • 63ad4ed: Refactor code.

2.2.0

Minor Changes

  • d5135c2: Update package version, refactor code.

2.1.0

Minor Changes

  • f05fc1b: Add passive = true for AddEventListenerOptions param

2.0.2

Patch Changes

  • 6fd9e50: Refactor code: remove uneccessary as const, remove uneccessary return, and some other minor fix.

2.0.1

Patch Changes

  • 39af3b5: Update Readme.md fix typo

2.0.0

Major Changes

  • 7da149c: Implement eslint, fix bugs exposed by eslint.

1.4.0

Minor Changes

  • d126a81: Update readme and package's keywords

1.3.0

Minor Changes

  • 2587d43: Move @types/node to devDependencies

1.2.0

Minor Changes

  • f8dac94: Add isDisabled param in case need to disable pull to refresh.

1.1.1

Patch Changes

  • 90660a8: Make error messgae more clear, supress error message on production env

1.1.0

Minor Changes

  • 9d974e6: Add custom maximumPullLength and refreshThreshold