✨ NEW: offset props, spy on particular div with parentScrollContainerRef prop

Author: pettiboy

README.md

@@ -68,12 +68,15 @@ import ScrollSpy from "react-ui-scrollspy";
 
 ## 💡 Props
 
-| Attributes         | Type                                       | Description                                                                                                            | Default | Required |
-| :----------------- | :----------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- | :------ | :------- |
-| `scrollThrottle`   | `number`                                   | in `milliseconds` to throttle the `onscroll` event. Lower the number, better the response, higher the performance cost | 300     | no       |
-| `children`         | `ReactNode`                                | -                                                                                                                      | -       | yes      |
-| `navContainerRef`  | `MutableRefObject<HTMLDivElement \| null>` | `ref` to your navigation container containing items with `data-to-scrollspy-id` attributes                             | -       | no       |
-| `onUpdateCallback` | `(id: string) => void`                     | Executes this function whenever you scroll to an `Element`, callback returns the `id` of that `Element` as well        | -       | no       |
+| Attributes                 | Type                                       | Description                                                                                                            | Default | Required |
+| :------------------------- | :----------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- | :------ | :------- |
+| `children`                 | `ReactNode`                                | Each direct child `Element` should contain an `id`                                                                     | -       | yes      |
+| `scrollThrottle`           | `number`                                   | in `milliseconds` to throttle the `onscroll` event. Lower the number, better the response, higher the performance cost | 300     | no       |
+| `navContainerRef`          | `MutableRefObject<HTMLDivElement \| null>` | `ref` to your navigation container containing items with `data-to-scrollspy-id` attributes                             | -       | no       |
+| `onUpdateCallback`         | `(id: string) => void`                     | Executes this function whenever you scroll to an `Element`, callback returns the `id` of that `Element` as well        | -       | no       |
+| `parentScrollContainerRef` | `MutableRefObject<HTMLDivElement \| null>` | If you want to spy only on a particular scrollable `container (Element)` then pass a ref of the same to this prop      | -       | no       |
+| `offsetTop`                | `number`                                   | spy will be fired when it has been scrolled `offsetTop` beyond `50%` to the top of the containing element              | 0       | no       |
+| `offsetBottom`             | `number`                                   | spy will be fired when it has been scrolled `offsetBottom` beyond `50%` to the bottom of the containing element        | 0       | no       |
 
 ## 📝 Authors
 

demo-app/src/components/src/ScrollSpy/ScrollSpy.tsx

@@ -12,15 +12,21 @@ import { throttle } from "../utils/throttle";
 interface ScrollSpyProps {
   children: ReactNode;
   navContainerRef?: MutableRefObject<HTMLDivElement | null>;
+  parentScrollContainerRef?: MutableRefObject<HTMLDivElement | null>;
   scrollThrottle?: number;
   onUpdateCallback?: (id: string) => void;
+  offsetTop?: number;
+  offsetBottom?: number;
 }
 
 const ScrollSpy = ({
   children,
   navContainerRef,
+  parentScrollContainerRef,
   onUpdateCallback,
   scrollThrottle = 300,
+  offsetTop = 0,
+  offsetBottom = 0,
 }: ScrollSpyProps) => {
   const scrollContainerRef = useRef<HTMLDivElement | null>(null);
   const [navContainerItems, setNavContainerItems] = useState<NodeListOf<Element> | undefined>(); // prettier-ignore
@@ -58,12 +64,19 @@ const ScrollSpy = ({
     // loop over all children in scroll container
     for (let i = 0; i < scrollParentContainer.children.length; i++) {
       // get child element
-      const child = scrollParentContainer.children.item(i);
-      if (!child) continue;
-      const useChild = child as HTMLDivElement;
+      const useChild = scrollParentContainer.children.item(i) as HTMLDivElement;
+
+      const elementIsVisible = parentScrollContainerRef
+        ? isVisible(
+            useChild,
+            offsetTop,
+            offsetBottom,
+            parentScrollContainerRef?.current
+          )
+        : isVisible(useChild, offsetTop, offsetBottom);
 
       // check if the element is in the viewport
-      if (isVisible(useChild)) {
+      if (elementIsVisible) {
         // if so, get its ID
         const changeHighlightedItemId = useChild.id;
 
@@ -100,10 +113,18 @@ const ScrollSpy = ({
     }
   };
 
-  window.addEventListener(
-    "scroll",
-    throttle(checkAndUpdateActiveScrollSpy, scrollThrottle)
-  );
+  // listen for scroll event
+  parentScrollContainerRef
+    ? // if ref for scrollable div is provided
+      parentScrollContainerRef.current?.addEventListener(
+        "scroll",
+        throttle(checkAndUpdateActiveScrollSpy, scrollThrottle)
+      )
+    : // else listen for scroll in window
+      window.addEventListener(
+        "scroll",
+        throttle(checkAndUpdateActiveScrollSpy, scrollThrottle)
+      );
 
   return <div ref={scrollContainerRef}>{children}</div>;
 };

demo-app/src/components/src/utils/isVisible.ts

@@ -1,12 +1,25 @@
+import { MutableRefObject } from "react";
+
 // to check if the element is in viewport
-export const isVisible = (el: HTMLElement) => {
+export const isVisible = (
+  el: HTMLElement,
+  offsetTop: number,
+  offsetBottom: number,
+  scrollableComponentRef?: HTMLDivElement | null
+) => {
   const rectInView = el.getBoundingClientRect();
 
   // this decides how much of the element should be visible
-  const leniency = window.innerHeight * 0.5;
+  const leniency = scrollableComponentRef
+    ? scrollableComponentRef.offsetHeight * 0.5
+    : window.innerHeight * 0.5;
+
+  const useHeight = scrollableComponentRef
+    ? scrollableComponentRef.offsetHeight
+    : window.innerHeight;
 
   return (
-    rectInView.top + leniency >= 0 &&
-    rectInView.bottom - leniency <= window.innerHeight
+    rectInView.top + leniency + offsetTop >= 0 &&
+    rectInView.bottom - leniency - offsetBottom <= useHeight
   );
 };

dev.md

@@ -2,17 +2,34 @@
 
 make required updates in the `src` (root) directory.
 
-```
+```bash
 npm run build
 npm link
 cd demo-app
 npm link react-ui-scrollspy
 ```
 
-- [ ] callbacks
-- [ ] on scroll top and onscrollbottom fix
-- [ ] deploy test website on github pages
-- [ ] offset props
+## commit messages
+
+https://github.com/ahmadawais/Emoji-Log
+
+```bash
+git commit -m "✨ NEW: "
+git commit -m "👌 IMPROVE: "
+git commit -m "🐛 FIX: "
+git commit -m "📚 DOC: "
+git commit -m "🚀 RELEASE: "
+git commit -m "🤖 TEST: "
+git commit -m "‼️ BREAKING: "
+```
+
+- [x] callbacks
+- [x] offset props
+- [x] relative positioning handled
 - [ ] customise data attributes
 - [ ] description, keywords
-- [ ] changelog
+- [ ] deploy test website on github pages
+- [x] update docs
+- [ ] deploy as version 2
+
+- [ ] on scroll top and onscrollbottom fix