📝 Table of Contents

• About
• Features
• Getting Started
• Basic Usage
  • LazyGetFunction
  • SharedLazyArray
  • LazyList Component
• Advanced Usage
  • Using Typescript
• Reference
  • LazyList Props
  • LazyList Methods
• Examples
• Authors
• Acknowledgments

🧐 About

An automatically lazy loading list based on @huds0n/components's FlatList using Shared State.

✅ List of Features

• Familiar: Extends FlatList and behaves accordingly.
• Fluid: Smoothly lazy loads or refreshes as needed.
• Universal: Data stored independently so can used across multiple components.

🏁 Getting Started

Prerequisites

Works with any project implementing React 16.8 onwards

Installing

npm i @huds0n/lazy-list

🧑‍💻 Basic Usage

LazyGetFunction

In order for a LazyList to work, a lazyGetFunction needs to be defined. This is a function that returns data on the fly, typically from API services. It receives offset and returns an object containing the fetched data (data) and if data has ended (pageEnd), either synchronously or asynchronously.

const lazyGetFunction = async (offset) => {
  const data = /* data from external API */
  const pageEnd = /* from external API or calculated base on number of elements returned */

  return { data, pageEnd }
};

SharedLazyArray

LazyList uses a SharedLazyArray rather than data directly. The SharedLazyArray contains the data and, because it is based on Shared State, pushes updates to attached LazyLists on data change.

import { SharedLazyArray } from '@huds0n/lazy-list';

const ExampleLazyArray = new SharedLazyArray(lazyGetFunction);

LazyList Component

As stated above LazyList does not accept data, instead a SharedLazyArray is passed.

<LazyList
  SharedLazyArray={ExampleLazyArray}
  renderItem={({ item }) => (
    /* rendered item */
  )}
/>

Automatically this list will lazy load when end threshold is reached and refresh when pulled at top.

🧑‍🔬 Advanced Usage </a

Using Typescript

SharedLazyArray can be easily typed by passing an element type parameter.

type ExampleElementType = {
  value: number,
  ...ect
}

const ExampleLazyArray = new SharedLazyArray<ExampleElementType>(lazyGetFunction);

📖 Reference

LazyList Props

| Prop | Description | Type | | --------- | ------------------------------ | ------------------- | | data | Current data array | element array | | isError | If list is in an error state | boolean | | isLoading | If lazyGetFunction running | boolean | | pageEnd | If no more data via API | boolean |

LazyList Methods

| Methods/Param | Description | Return/Type | | -------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------- | | lazyGet | Runs lazyGetFunctionReturns null is already at pageEnd | { data: element array, pageEnd: boolean } or null | | options (optional) | A reset flag can be passed here | { reset?: boolean } | | | | | | Reset | Resets LazyList | void | | | | | | useArray | Hook at registers a component to update whenever the list changes | LazyList Props |

📲 Example

Clone or fork the repo at https://github.com/JontiHudson/modules-huds0n-lazy-list

Go to the __example__ folder. Run npm install to install the expo project, then expo start to launch the example.

✍️ Authors

• @JontiHudson - Idea & Initial work
• @MartinHudson - Support & Development

See also the list of contributors who participated in this project.

🎉 Acknowledgements

• Special thanks to my fiance, Arma, who has been so patient with all my extra-curricular work.