feat: add special prop for passing refs to integrations

Author: danielwaltz

README.md

@@ -77,13 +77,13 @@ import { useAdhesive } from '@adhesivejs/react';
 import { useRef } from 'react';
 
 export function App() {
-  const targetEl = useRef<HTMLElement>(null);
+  const targetRef = useRef<HTMLElement>(null);
 
-  useAdhesive(targetEl, { position: 'top' });
+  useAdhesive(targetRef, { position: 'top' });
 
   return (
     <div>
-      <header ref={targetEl}>This header will stick to the top</header>
+      <header ref={targetRef}>This header will stick to the top</header>
 
       <main>
         <p>Your main content here...</p>
@@ -122,9 +122,9 @@ import { AdhesiveContainer } from '@adhesivejs/vue';
 import { useAdhesive } from '@adhesivejs/vue';
 import { useTemplateRef } from 'vue';
 
-const targetEl = useTemplateRef('target');
+const targetRef = useTemplateRef('target');
 
-useAdhesive(targetEl, { position: 'top' });
+useAdhesive(targetRef, { position: 'top' });
 </script>
 
 <template>
@@ -176,4 +176,3 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 ## 📄 License
 
 This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
-

packages/react/README.md

@@ -66,15 +66,15 @@ import { useAdhesive, type AdhesivePosition } from '@adhesivejs/react';
 import { useRef, useState } from 'react';
 
 export function App() {
-  const targetEl = useRef<HTMLDivElement>(null);
-  const boundingEl = useRef<HTMLDivElement>(null);
+  const targetRef = useRef<HTMLDivElement>(null);
+  const boundingRef = useRef<HTMLDivElement>(null);
   const [enabled, setEnabled] = useState(true);
   const [position, setPosition] = useState<AdhesivePosition>('top');
 
   useAdhesive(
-    targetEl,
+    targetRef,
     {
-      boundingEl,
+      boundingRef,
       position,
       offset: 20,
       enabled,
@@ -85,7 +85,7 @@ export function App() {
   );
 
   return (
-    <div ref={boundingEl} style={{ height: '200vh' }}>
+    <div ref={boundingRef} style={{ height: '200vh' }}>
       <button onClick={() => setEnabled(!enabled)}>
         {enabled ? 'Disable' : 'Enable'} Sticky
       </button>
@@ -94,7 +94,7 @@ export function App() {
         Switch to {position === 'top' ? 'bottom' : 'top'}
       </button>
 
-      <div ref={targetEl} className="sticky-element">
+      <div ref={targetRef} className="sticky-element">
         <h2>Dynamic Sticky Element</h2>
         <p>Position: {position} | Enabled: {enabled ? 'Yes' : 'No'}</p>
       </div>
@@ -141,7 +141,8 @@ For more control over the sticky behavior.
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `boundingEl` | `React.RefObject` \| `string` | `undefined` | The element that defines the sticky boundaries |
+| `boundingRef` | `React.RefObject` \| `HTMLElement` \| `string` | `document.body` | The element that defines the sticky boundaries |
+| `boundingEl` | `HTMLElement` \| `string` | `document.body` | Alternative way to specify bounding element (for compatibility) |
 | `position` | `'top' \| 'bottom'` | `'top'` | Where the element should stick |
 | `offset` | `number` | `0` | Offset in pixels from the position |
 | `zIndex` | `number` | `1` | Z-index for the fixed element |

packages/react/src/components/AdhesiveContainer.tsx

@@ -16,6 +16,7 @@ export type AdhesiveContainerProps = Partial<UseAdhesiveOptions> &
  * ```
  */
 export function AdhesiveContainer({
+  boundingRef,
   boundingEl,
   enabled = true,
   offset,
@@ -32,6 +33,7 @@ export function AdhesiveContainer({
 
   const options = useMemo<UseAdhesiveOptions>(
     () => ({
+      boundingRef,
       boundingEl,
       enabled,
       offset,
@@ -43,6 +45,7 @@ export function AdhesiveContainer({
       releasedClassName,
     }),
     [
+      boundingRef,
       boundingEl,
       enabled,
       offset,

packages/react/src/hooks/useAdhesive.ts

@@ -5,10 +5,8 @@ import {
   type MaybeElementOrSelectorRef,
 } from "../utils/unrefElement.js";
 
-export type UseAdhesiveOptions = Partial<
-  Omit<AdhesiveOptions, "targetEl" | "boundingEl">
-> & {
-  boundingEl?: AdhesiveOptions["boundingEl"] | MaybeElementOrSelectorRef;
+export type UseAdhesiveOptions = Partial<Omit<AdhesiveOptions, "targetEl">> & {
+  boundingRef?: MaybeElementOrSelectorRef;
 };
 
 /**
@@ -27,17 +25,17 @@ export type UseAdhesiveOptions = Partial<
  * import { useAdhesive } from '@adhesivejs/react';
  *
  * function Component() {
- *   const targetEl = useRef<HTMLDivElement>(null);
- *   const boundingEl = useRef<HTMLDivElement>(null);
+ *   const targetRef = useRef<HTMLDivElement>(null);
+ *   const boundingRef = useRef<HTMLDivElement>(null);
  *
  *   useAdhesive(
- *     targetEl,
- *     { boundingEl, position: 'top' }
+ *     targetRef,
+ *     { boundingRef, position: 'top' }
  *   );
  *
  *   return (
- *     <div ref={boundingEl}>
- *       <div ref={targetEl}>Sticky content</div>
+ *     <div ref={boundingRef}>
+ *       <div ref={targetRef}>Sticky content</div>
  *     </div>
  *   );
  * }
@@ -49,7 +47,8 @@ export function useAdhesive(
 ) {
   function getValidatedOptions() {
     const targetEl = unrefElement(target);
-    const boundingEl = unrefElement(options?.boundingEl);
+    const boundingEl =
+      unrefElement(options?.boundingRef) ?? options?.boundingEl;
 
     if (!targetEl) {
       throw new Error("@adhesivejs/react: sticky element is not defined");

packages/react/src/utils/unrefElement.ts

@@ -1,9 +1,7 @@
 import type { RefObject } from "react";
 
-type MaybeElementRefObject = RefObject<HTMLElement | HTMLDivElement | null>;
-
 export type MaybeElementOrSelectorRef =
-  | MaybeElementRefObject
+  | RefObject<HTMLElement | null>
   | HTMLElement
   | string
   | null

packages/vue/README.md

@@ -71,15 +71,15 @@ import { AdhesiveContainer } from '@adhesivejs/vue';
 import { useAdhesive, type AdhesivePosition } from '@adhesivejs/vue';
 import { ref, useTemplateRef } from 'vue';
 
-const targetEl = useTemplateRef('target');
-const boundingEl = useTemplateRef('bounding');
+const targetRef = useTemplateRef('target');
+const boundingRef = useTemplateRef('bounding');
 const enabled = ref(true);
 const position = ref<AdhesivePosition>('top');
 
 useAdhesive(
-  targetEl,
+  targetRef,
   () => ({
-    boundingEl: boundingEl.value,
+    boundingRef: boundingRef.value,
     position: position.value,
     offset: 20,
     enabled: enabled.value,
@@ -148,7 +148,8 @@ For more control over the sticky behavior with full Vue reactivity support.
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `boundingEl` | `TemplateRef` \| `string` | `undefined` | The element that defines the sticky boundaries |
+| `boundingRef` | `TemplateRef` \| `HTMLElement` \| `string` | `document.body` | The element that defines the sticky boundaries |
+| `boundingEl` | `HTMLElement` \| `string` | `document.body` | Alternative way to specify bounding element (for compatibility) |
 | `position` | `'top' \| 'bottom'` | `'top'` | Where the element should stick |
 | `offset` | `number` | `0` | Offset in pixels from the position |
 | `zIndex` | `number` | `1` | Z-index for the fixed element |

packages/vue/src/components/AdhesiveContainer.vue

@@ -35,6 +35,7 @@ export default { name: "AdhesiveContainer" };
 
 <script setup lang="ts">
 const {
+  boundingRef,
   boundingEl,
   enabled = true,
   offset,
@@ -49,6 +50,7 @@ const {
 const targetRef = useTemplateRef("target");
 
 const options = computed<UseAdhesiveOptions>(() => ({
+  boundingRef,
   boundingEl,
   enabled,
   offset,

packages/vue/src/composables/useAdhesive.ts

@@ -11,10 +11,8 @@ import {
   type MaybeElementOrSelectorRef,
 } from "../utils/unrefElement.js";
 
-export type UseAdhesiveOptions = Partial<
-  Omit<AdhesiveOptions, "targetEl" | "boundingEl">
-> & {
-  boundingEl?: AdhesiveOptions["boundingEl"] | MaybeElementOrSelectorRef;
+export type UseAdhesiveOptions = Partial<Omit<AdhesiveOptions, "targetEl">> & {
+  boundingRef?: MaybeElementOrSelectorRef;
 };
 
 /**
@@ -33,12 +31,12 @@ export type UseAdhesiveOptions = Partial<
  * import { useTemplateRef } from 'vue';
  * import { useAdhesive } from '@adhesivejs/vue';
  *
- * const targetEl = useTemplateRef('target');
- * const boundingEl = useTemplateRef('bounding');
+ * const targetRef = useTemplateRef('target');
+ * const boundingRef = useTemplateRef('bounding');
  *
  * useAdhesive(
- *   targetEl,
- *   () => ({ boundingEl: boundingEl.value, position: 'top' })
+ *   targetRef,
+ *   () => ({ boundingRef: boundingRef.value, position: 'top' })
  * );
  * </script>
  *
@@ -55,12 +53,12 @@ export type UseAdhesiveOptions = Partial<
  * import { ref } from 'vue';
  * import { useAdhesive } from '@adhesivejs/vue';
  *
- * const targetEl = useTemplateRef('target');
+ * const targetRef = useTemplateRef('target');
  * const enabled = ref(true);
  * const offset = ref(10);
  *
  * // Reactive options
- * useAdhesive(targetEl, () => ({
+ * useAdhesive(targetRef, () => ({
  *   position: 'top',
  *   enabled: enabled.value,
  *   offset: offset.value,
@@ -76,7 +74,8 @@ export function useAdhesive(
     const optionsValue = toValue(options);
 
     const targetEl = unrefElement(target);
-    const boundingEl = unrefElement(optionsValue?.boundingEl);
+    const boundingEl =
+      unrefElement(optionsValue?.boundingRef) ?? optionsValue?.boundingEl;
 
     if (!targetEl) {
       throw new Error("@adhesivejs/vue: sticky element is not defined");

playground/react/src/App.tsx

@@ -13,10 +13,10 @@ export function App() {
   const [enabled, setEnabled] = useState(true);
   const [position, setPosition] = useState<AdhesivePosition>("top");
 
-  const targetEl = useRef<HTMLDivElement>(null);
-  const boundingEl = useRef<HTMLDivElement>(null);
+  const targetRef = useRef<HTMLDivElement>(null);
+  const boundingRef = useRef<HTMLDivElement>(null);
 
-  useAdhesive(targetEl, { boundingEl, enabled, position });
+  useAdhesive(targetRef, { boundingRef, enabled, position });
 
   return (
     <div>
@@ -31,8 +31,8 @@ export function App() {
       </button>
       <br />
       <br />
-      <div ref={boundingEl}>
-        <div ref={targetEl}>Sticky Element</div>
+      <div ref={boundingRef}>
+        <div ref={targetRef}>Sticky Element</div>
         <a href="https://vite.dev" target="_blank" rel="noopener noreferrer">
           <img src={viteLogo} className="logo" alt="Vite logo" />
         </a>

playground/vue/src/App.vue

@@ -10,11 +10,11 @@ const count = ref(0);
 const enabled = ref(true);
 const position = ref<AdhesivePosition>("top");
 
-const targetEl = useTemplateRef("target");
-const boundingEl = useTemplateRef("bounding");
+const targetRef = useTemplateRef("target");
+const boundingRef = useTemplateRef("bounding");
 
-useAdhesive(targetEl, () => ({
-  boundingEl: boundingEl.value,
+useAdhesive(targetRef, () => ({
+  boundingRef: boundingRef.value,
   enabled: enabled.value,
   position: position.value,
 }));
@@ -25,7 +25,10 @@ useAdhesive(targetEl, () => ({
     <button type="button" @click="enabled = !enabled">
       {{ enabled ? "Disable" : "Enable" }} Sticky
     </button>
-    <button type="button" @click="position === 'top' ? 'bottom' : 'top'">
+    <button
+      type="button"
+      @click="position = position === 'top' ? 'bottom' : 'top'"
+    >
       Switch to {{ position === "top" ? "bottom" : "top" }}
     </button>
     <br />