README.md

@bentoo/react-lazy

A lightweight and flexible React lazy loading library.
Load components or images only when they enter the viewport, improving performance, reducing initial bundle size, and providing optional callbacks when elements become visible.

---

Features

• Lazy load any component or element in React.
• Optional fallback content while loading.
• Callback support when an element becomes visible.
• Works with Next.js, React 18, and TypeScript.
• Lightweight, fully typed, and tree-shakable.

---

Installation

npm install @bentoo/react-lazy
# or
yarn add @bentoo/react-lazy
# or
pnpm add @bentoo/react-lazy

---

Usage

1. LazyComponent

Lazy load any React component with a fallback:

import React from 'react';
import { LazyComponent } from '@bentoo/react-lazy';

export default function App() {
  return (
    <div>
      <h1>My content</h1>
      <LazyComponent fallback={<h2>Loading...</h2>}>
        <img src="/myPicture.png" alt="MyPicture" />
      </LazyComponent>
    </div>
  );
}

Props:

Prop	Type	Description
children	ReactNode	Content to display after lazy load.
fallback	ReactNode	Content displayed while loading.

---

2. LazyImage

Lazy load images with optional placeholder, blur, fade-in, and Next.js support:

import { LazyImage } from '@bentoo/react-lazy';
// For Next.js, pass ImageComponent={NextImage}

<LazyImage
  src="/photo.jpg"
  alt="My Photo"
  width={600}
  height={400}
  placeholder="/photo-low.jpg"
  blur
/>

Props:

Prop	Type	Description
src	string	Image source
alt	string	Image alt text
width/height	number	Optional width/height
placeholder	string	Low-res placeholder for blur effect
blur	boolean	Apply blur to placeholder
ImageComponent	React Component	Optional (pass next/image in Next.js)

---

3. Lazy with Callback

Trigger a function when an element enters the viewport:

import { useLazyCallback } from '@bentoo/react-lazy';

export default function Section() {
  const { ref } = useLazyCallback({
    onVisible: () => console.log('Element is now visible!'),
    triggerOnce: true
  });

  return <div ref={ref}>Watch me appear!</div>;
}

---

Next.js Example

import Image from 'next/image';
import { LazyImage } from '@bentoo/react-lazy';

export default function NextApp() {
  return (
    <LazyImage
      ImageComponent={Image}
      src="/photo.jpg"
      alt="Next.js Image"
      width={600}
      height={400}
      placeholder="/photo-low.jpg"
      blur
    />
  );
}

Note: next/image already supports lazy loading, but LazyImage adds viewport-triggered effects and callbacks.

---

Contribution

We welcome contributions!

1. Fork the repository
2. Create a feature branch (git checkout -b my-feature)
3. Commit your changes (git commit -m 'Add feature')
4. Push to the branch (git push origin my-feature)
5. Open a Pull Request

---

License

MIT License – see the LICENSE file for details.