use-pull-to-refresh

Use Pull To Refresh

Table of contents

• Table of contents
• Description
• Purposes
• Prerequisites
• Getting Started
  • What's the different to other similar packages?
• Installation
• Usage
• API
  • Parameters
  • Return Type
• Change log
• Authors
• License

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?

• react-pull-to-refresh : will run into error 'window' is not defined when using with NextJs SSR.
• react-hooks-pull-to-refresh, react-pull-updown-to-refresh, react-web-pull-to-refresh : Either being unmaintained or doesn't support Typescript, or newer version of React.
• react-native-pull-refresh-android : solution only available for react native.

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

• Pleach check here

Authors

• Senbonzakura1234 - Initial work - Senbonzakura1234

License

MIT License © Senbonzakura1234

Changelog

2.4.1

Patch Changes

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