@quiltt/react 4.0.1 → 4.2.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @quiltt/react
 
+## 4.2.0
+
+### Minor Changes
+
+- [#348](https://github.com/quiltt/quiltt-js/pull/348) [`7e27845`](https://github.com/quiltt/quiltt-js/commit/7e2784523124c87fc6654d8336f924286daade1b) Thanks [@zubairaziz](https://github.com/zubairaziz)! - resolve connectionId persistence issue in QuilttContainer
+
+### Patch Changes
+
+- Updated dependencies [[`7e27845`](https://github.com/quiltt/quiltt-js/commit/7e2784523124c87fc6654d8336f924286daade1b)]:
+  - @quiltt/core@4.2.0
+
+## 4.1.0
+
+### Minor Changes
+
+- [#342](https://github.com/quiltt/quiltt-js/pull/342) [`6a387ba`](https://github.com/quiltt/quiltt-js/commit/6a387ba0db77912df85c6cd1924f63edf50f9cdd) Thanks [@sirwolfgang](https://github.com/sirwolfgang)! - Create useQuilttInstitutions hook
+
+### Patch Changes
+
+- Updated dependencies [[`6a387ba`](https://github.com/quiltt/quiltt-js/commit/6a387ba0db77912df85c6cd1924f63edf50f9cdd)]:
+  - @quiltt/core@4.1.0
+
 ## 4.0.1
 
 ### Patch Changes

package/dist/{QuilttAuthProvider-client-CER-TOln.js → QuilttAuthProvider-client-DLARZukU.js}

@@ -6,7 +6,7 @@ import './QuilttSettings-client-BK-0SQME.js';
 import './useSession-client-CCAvnROP.js';
 import { jsx } from 'react/jsx-runtime';
 import { ApolloProvider } from '@apollo/client/react/context/ApolloProvider.js';
-import { u as useQuilttSession } from './useQuilttSession-client-D2mjVT4S.js';
+import { u as useQuilttSession } from './useQuilttSession-client-Ddb55W0n.js';
 
 const useIdentifySession = (auth, setSession)=>{
     const identifySession = useCallback(async (payload, callbacks)=>{
@@ -187,4 +187,4 @@ const useRevokeSession = (auth, session, setSession)=>{
     });
 };
 
-export { QuilttAuthProvider as Q, useIdentifySession as a, useAuthenticateSession as b, useRevokeSession as c, useImportSession as u };
+export { QuilttAuthProvider as Q, useIdentifySession as a, useAuthenticateSession as b, useRevokeSession as c, isDeepEqual as i, useImportSession as u };

package/dist/index.d.ts

@@ -133,6 +133,12 @@ type BaseQuilttButtonProps<T extends ElementType> = {
     connectorId: string;
     connectionId?: string;
     institution?: string;
+    /**
+     * Forces complete remount when connectionId changes.
+     * Useful as a fallback for ensuring clean state.
+     * @default false
+     */
+    forceRemountOnConnectionChange?: boolean;
     onClick?: (event: MouseEvent<HTMLElement>) => void;
 };
 type QuilttCallbackProps = Omit<ConnectorSDKCallbacks, 'onLoad'> & {
@@ -140,18 +146,35 @@ type QuilttCallbackProps = Omit<ConnectorSDKCallbacks, 'onLoad'> & {
     onHtmlLoad?: React.ReactEventHandler<HTMLElement>;
 };
 type QuilttButtonProps<T extends ElementType> = PropsWithChildren<BaseQuilttButtonProps<T> & QuilttCallbackProps>;
-declare const QuilttButton: <T extends ElementType = "button">({ as, connectorId, connectionId, institution, onEvent, onOpen, onLoad, onExit, onExitSuccess, onExitAbort, onExitError, onClick, onHtmlLoad, children, ...props }: QuilttButtonProps<T> & PropsOf<T>) => react_jsx_runtime.JSX.Element;
+/**
+ * QuilttButton provides a clickable interface to open Quiltt connectors.
+ *
+ * When connectionId changes, the button will automatically update the existing
+ * connector instance with the new connection details. If you need to force a
+ * complete remount instead, set forceRemountOnConnectionChange to true.
+ */
+declare const QuilttButton: <T extends ElementType = "button">({ as, connectorId, connectionId, institution, forceRemountOnConnectionChange, onEvent, onOpen, onLoad, onExit, onExitSuccess, onExitAbort, onExitError, onClick, onHtmlLoad, children, ...props }: QuilttButtonProps<T> & PropsOf<T>) => react_jsx_runtime.JSX.Element;
 
 type QuilttContainerProps<T extends ElementType> = PropsWithChildren<{
     as?: T;
     connectorId: string;
     connectionId?: string;
+    /**
+     * Forces complete remount when connectionId changes.
+     * Useful as a fallback for ensuring clean state.
+     * @default false
+     */
+    forceRemountOnConnectionChange?: boolean;
 } & ConnectorSDKCallbacks>;
 /**
  * QuilttContainer uses globally shared callbacks. It's recommended you only use
  * one Container at a time.
+ *
+ * When connectionId changes, the container will automatically update the existing
+ * connector instance with the new connection details. If you need to force a
+ * complete remount instead, set forceRemountOnConnectionChange to true.
  */
-declare const QuilttContainer: <T extends ElementType = "div">({ as, connectorId, connectionId, onEvent, onLoad, onExit, onExitSuccess, onExitAbort, onExitError, children, ...props }: QuilttContainerProps<T> & PropsOf<T>) => react_jsx_runtime.JSX.Element;
+declare const QuilttContainer: <T extends ElementType = "div">({ as, connectorId, connectionId, forceRemountOnConnectionChange, onEvent, onLoad, onExit, onExitSuccess, onExitAbort, onExitError, children, ...props }: QuilttContainerProps<T> & PropsOf<T>) => react_jsx_runtime.JSX.Element;
 
 export { QuilttAuthProvider, QuilttButton, QuilttContainer, QuilttProvider, QuilttSettingsProvider, useAuthenticateSession, useEventListener, useIdentifySession, useImportSession, useIsomorphicLayoutEffect, useQuilttClient, useQuilttConnector, useQuilttSession, useQuilttSettings, useRevokeSession, useSession, useStorage };
 export type { AuthenticateSession, IdentifySession, ImportSession, RevokeSession, SetSession, UseQuilttSession };

package/dist/index.js

@@ -1,16 +1,17 @@
 export * from '@quiltt/core';
 export { u as useEventListener } from './useEventListener-client-DVM5xwKY.js';
 export { u as useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect-client-DeTHOKz1.js';
-import { Q as QuilttAuthProvider } from './QuilttAuthProvider-client-CER-TOln.js';
-export { b as useAuthenticateSession, a as useIdentifySession, u as useImportSession, c as useRevokeSession } from './QuilttAuthProvider-client-CER-TOln.js';
+import { Q as QuilttAuthProvider, i as isDeepEqual } from './QuilttAuthProvider-client-DLARZukU.js';
+export { b as useAuthenticateSession, a as useIdentifySession, u as useImportSession, c as useRevokeSession } from './QuilttAuthProvider-client-DLARZukU.js';
 export { u as useQuilttClient } from './useQuilttClient-client-CAAUait1.js';
-import { u as useQuilttConnector } from './useQuilttConnector-client-sRplTzek.js';
-export { u as useQuilttSession } from './useQuilttSession-client-D2mjVT4S.js';
+import { u as useQuilttConnector } from './useQuilttConnector-client-BK7ybRZe.js';
+export { u as useQuilttSession } from './useQuilttSession-client-Ddb55W0n.js';
 export { u as useQuilttSettings } from './useQuilttSettings-client-BOCBjFXe.js';
 export { u as useSession } from './useSession-client-CCAvnROP.js';
 export { u as useStorage } from './useStorage-client-DHcq3Kuh.js';
 import { jsx } from 'react/jsx-runtime';
 import { Q as QuilttSettingsProvider } from './QuilttSettingsProvider-client-Va7uJ_dQ.js';
+import { useRef, useEffect } from 'react';
 
 const QuilttProvider = ({ clientId, token, children })=>{
     return /*#__PURE__*/ jsx(QuilttSettingsProvider, {
@@ -22,7 +23,46 @@ const QuilttProvider = ({ clientId, token, children })=>{
     });
 };
 
-const QuilttButton = ({ as, connectorId, connectionId, institution, onEvent, onOpen, onLoad, onExit, onExitSuccess, onExitAbort, onExitError, onClick, onHtmlLoad, children, ...props })=>{
+/**
+ * QuilttButton provides a clickable interface to open Quiltt connectors.
+ *
+ * When connectionId changes, the button will automatically update the existing
+ * connector instance with the new connection details. If you need to force a
+ * complete remount instead, set forceRemountOnConnectionChange to true.
+ */ const QuilttButton = ({ as, connectorId, connectionId, institution, forceRemountOnConnectionChange = false, onEvent, onOpen, onLoad, onExit, onExitSuccess, onExitAbort, onExitError, onClick, onHtmlLoad, children, ...props })=>{
+    // Keep track of previous connectionId for change detection
+    const prevConnectionIdRef = useRef(connectionId);
+    const prevCallbacksRef = useRef({
+        onEvent,
+        onOpen,
+        onLoad,
+        onExit,
+        onExitSuccess,
+        onExitAbort,
+        onExitError
+    });
+    // Track if callbacks have changed to help with debugging
+    const currentCallbacks = {
+        onEvent,
+        onOpen,
+        onLoad,
+        onExit,
+        onExitSuccess,
+        onExitAbort,
+        onExitError
+    };
+    const callbacksChanged = !isDeepEqual(prevCallbacksRef.current, currentCallbacks);
+    useEffect(()=>{
+        prevCallbacksRef.current = currentCallbacks;
+    });
+    // Warning for potential callback reference issues
+    useEffect(()=>{
+        if (callbacksChanged && prevConnectionIdRef.current !== undefined) {
+            console.warn('[Quiltt] Callback functions changed after initial render. ' + 'This may cause unexpected behavior. Consider memoizing callback functions ' + 'with useCallback to maintain stable references.');
+        }
+    }, [
+        callbacksChanged
+    ]);
     const { open } = useQuilttConnector(connectorId, {
         connectionId,
         institution,
@@ -35,6 +75,12 @@ const QuilttButton = ({ as, connectorId, connectionId, institution, onEvent, onO
         onExitAbort,
         onExitError
     });
+    // Update previous connectionId reference
+    useEffect(()=>{
+        prevConnectionIdRef.current = connectionId;
+    }, [
+        connectionId
+    ]);
     const Button = as || 'button';
     const handleClick = (event)=>{
         // Call the user's onClick handler first to allow for:
@@ -45,20 +91,58 @@ const QuilttButton = ({ as, connectorId, connectionId, institution, onEvent, onO
         // Then open the Quiltt connector
         open();
     };
+    // Generate key for forced remounting if enabled, but respect user-provided key
+    const buttonKey = props.key ?? (forceRemountOnConnectionChange ? `${connectorId}-${connectionId || 'no-connection'}` : undefined);
     return /*#__PURE__*/ jsx(Button, {
         onClick: handleClick,
         onLoad: onHtmlLoad,
         "quiltt-connection": connectionId,
         ...props,
         children: children
-    });
+    }, buttonKey);
 };
 
 /**
  * QuilttContainer uses globally shared callbacks. It's recommended you only use
  * one Container at a time.
- */ const QuilttContainer = ({ as, connectorId, connectionId, onEvent, onLoad, onExit, onExitSuccess, onExitAbort, onExitError, children, ...props })=>{
+ *
+ * When connectionId changes, the container will automatically update the existing
+ * connector instance with the new connection details. If you need to force a
+ * complete remount instead, set forceRemountOnConnectionChange to true.
+ */ const QuilttContainer = ({ as, connectorId, connectionId, forceRemountOnConnectionChange = false, onEvent, onLoad, onExit, onExitSuccess, onExitAbort, onExitError, children, ...props })=>{
+    // Keep track of previous connectionId for change detection
+    const prevConnectionIdRef = useRef(connectionId);
+    const prevCallbacksRef = useRef({
+        onEvent,
+        onLoad,
+        onExit,
+        onExitSuccess,
+        onExitAbort,
+        onExitError
+    });
+    // Track if callbacks have changed to help with debugging
+    const currentCallbacks = {
+        onEvent,
+        onLoad,
+        onExit,
+        onExitSuccess,
+        onExitAbort,
+        onExitError
+    };
+    const callbacksChanged = !isDeepEqual(prevCallbacksRef.current, currentCallbacks);
+    useEffect(()=>{
+        prevCallbacksRef.current = currentCallbacks;
+    });
+    // Warning for potential callback reference issues
+    useEffect(()=>{
+        if (callbacksChanged && prevConnectionIdRef.current !== undefined) {
+            console.warn('[Quiltt] Callback functions changed after initial render. ' + 'This may cause unexpected behavior. Consider memoizing callback functions ' + 'with useCallback to maintain stable references.');
+        }
+    }, [
+        callbacksChanged
+    ]);
     useQuilttConnector(connectorId, {
+        connectionId,
         nonce: props?.nonce,
         onEvent,
         onLoad,
@@ -67,13 +151,21 @@ const QuilttButton = ({ as, connectorId, connectionId, institution, onEvent, onO
         onExitAbort,
         onExitError
     });
+    // Update previous connectionId reference
+    useEffect(()=>{
+        prevConnectionIdRef.current = connectionId;
+    }, [
+        connectionId
+    ]);
     const Container = as || 'div';
+    // Generate key for forced remounting if enabled, but respect user-provided key
+    const containerKey = props.key ?? (forceRemountOnConnectionChange ? `${connectorId}-${connectionId || 'no-connection'}` : undefined);
     return /*#__PURE__*/ jsx(Container, {
         "quiltt-container": connectorId,
         "quiltt-connection": connectionId,
         ...props,
         children: children
-    });
+    }, containerKey);
 };
 
 export { QuilttAuthProvider, QuilttButton, QuilttContainer, QuilttProvider, QuilttSettingsProvider, useQuilttConnector };

package/dist/{useQuilttConnector-client-sRplTzek.js → useQuilttConnector-client-BK7ybRZe.js}

@@ -1,45 +1,74 @@
 'use client';
-import { useState, useEffect, useCallback } from 'react';
+import { useState, useRef, useEffect, useCallback } from 'react';
 import { cdnBase } from '@quiltt/core';
-import { u as useQuilttSession } from './useQuilttSession-client-D2mjVT4S.js';
+import { u as useQuilttSession } from './useQuilttSession-client-Ddb55W0n.js';
 import { u as useScript } from './useScript-client-JCgaTW9n.js';
 
-var version = "4.0.1";
+var version = "4.2.0";
 
 const useQuilttConnector = (connectorId, options)=>{
     const status = useScript(`${cdnBase}/v1/connector.js?agent=react-${version}`, {
         nonce: options?.nonce
     });
-    const { session } = useQuilttSession();
+    // This ensures we're not destructuring `session` before the script has loaded
+    const useQuilttSessionReturn = useQuilttSession();
+    const session = useQuilttSessionReturn?.session || null;
     const [connector, setConnector] = useState();
     const [isOpening, setIsOpening] = useState(false);
+    // Keep track of the previous connectionId to detect changes
+    const prevConnectionIdRef = useRef(options?.connectionId);
+    const prevConnectorIdRef = useRef(connectorId);
+    const connectorCreatedRef = useRef(false);
     // Set Session
-    // biome-ignore lint/correctness/useExhaustiveDependencies: We also need to update on status change
     useEffect(()=>{
         if (typeof Quiltt === 'undefined') return;
+        console.debug('[Quiltt] script status: ', status);
         Quiltt.authenticate(session?.token);
     }, [
         status,
         session?.token
     ]);
     // Set Connector
-    // biome-ignore lint/correctness/useExhaustiveDependencies: We also need to update on status change
     useEffect(()=>{
         if (typeof Quiltt === 'undefined' || !connectorId) return;
-        if (options?.connectionId) {
-            setConnector(Quiltt.reconnect(connectorId, {
-                connectionId: options.connectionId
-            }));
-        } else {
-            setConnector(Quiltt.connect(connectorId, {
-                institution: options?.institution
-            }));
+        console.debug('[Quiltt] script status: ', status);
+        const currentConnectionId = options?.connectionId;
+        const currentInstitution = options?.institution;
+        // Check if this is a connectionId change on the same connector
+        const connectionIdChanged = prevConnectionIdRef.current !== currentConnectionId;
+        const connectorIdChanged = prevConnectorIdRef.current !== connectorId;
+        // If only connectionId changed (not the connectorId), the core SDK should handle this
+        // via the updated Handler.updateOptions method, so we don't need to recreate the connector
+        if (connectionIdChanged && !connectorIdChanged && connectorCreatedRef.current) {
+            // The SDK will automatically update the existing handler with new connectionId
+            // via the DocumentObserver -> Engine.onChange -> Handler.updateOptions flow
+            console.debug('[Quiltt] connectionId changed, SDK will handle update automatically');
+            // Update our refs
+            prevConnectionIdRef.current = currentConnectionId;
+            return;
+        }
+        // Only create new connector if we haven't created one yet or if connectorId changed
+        if (!connectorCreatedRef.current || connectorIdChanged) {
+            // Create new connector (initial mount or connectorId changed)
+            if (currentConnectionId) {
+                setConnector(Quiltt.reconnect(connectorId, {
+                    connectionId: currentConnectionId
+                }));
+            } else {
+                setConnector(Quiltt.connect(connectorId, {
+                    institution: currentInstitution
+                }));
+            }
+            connectorCreatedRef.current = true;
         }
+        // Update refs
+        prevConnectionIdRef.current = currentConnectionId;
+        prevConnectorIdRef.current = connectorId;
     }, [
-        status,
         connectorId,
         options?.connectionId,
-        options?.institution
+        options?.institution,
+        status
     ]);
     // onEvent
     useEffect(()=>{

package/dist/{useQuilttSession-client-D2mjVT4S.js → useQuilttSession-client-Ddb55W0n.js}

@@ -1,7 +1,7 @@
 'use client';
 import { useCallback } from 'react';
 import { AuthAPI } from '@quiltt/core';
-import { u as useImportSession, a as useIdentifySession, b as useAuthenticateSession, c as useRevokeSession } from './QuilttAuthProvider-client-CER-TOln.js';
+import { u as useImportSession, a as useIdentifySession, b as useAuthenticateSession, c as useRevokeSession } from './QuilttAuthProvider-client-DLARZukU.js';
 import { u as useQuilttSettings } from './useQuilttSettings-client-BOCBjFXe.js';
 import { u as useSession } from './useSession-client-CCAvnROP.js';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quiltt/react",
-  "version": "4.0.1",
+  "version": "4.2.0",
   "description": "React Components and Hooks for Quiltt Connector",
   "keywords": [
     "quiltt",
@@ -35,7 +35,8 @@
   "main": "dist/index.js",
   "dependencies": {
     "@apollo/client": "^3.12.4",
-    "@quiltt/core": "4.0.1"
+    "use-debounce": "^10.0.4",
+    "@quiltt/core": "4.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "1.9.4",

package/src/components/QuilttButton.tsx

@@ -1,9 +1,11 @@
+import { useEffect, useRef } from 'react'
 import type { ElementType, MouseEvent, PropsWithChildren } from 'react'
 
 import type { ConnectorSDKCallbacks } from '@quiltt/core'
 
 import { useQuilttConnector } from '@/hooks/useQuilttConnector'
 import type { PropsOf } from '@/types'
+import { isDeepEqual } from '@/utils/isDeepEqual'
 
 // Base button props without callback-specific properties
 type BaseQuilttButtonProps<T extends ElementType> = {
@@ -11,6 +13,14 @@ type BaseQuilttButtonProps<T extends ElementType> = {
   connectorId: string
   connectionId?: string // For Reconnect Mode
   institution?: string // For Connect Mode
+
+  /**
+   * Forces complete remount when connectionId changes.
+   * Useful as a fallback for ensuring clean state.
+   * @default false
+   */
+  forceRemountOnConnectionChange?: boolean
+
   // Override the native onClick handler
   onClick?: (event: MouseEvent<HTMLElement>) => void
 }
@@ -27,11 +37,19 @@ type QuilttButtonProps<T extends ElementType> = PropsWithChildren<
   BaseQuilttButtonProps<T> & QuilttCallbackProps
 >
 
+/**
+ * QuilttButton provides a clickable interface to open Quiltt connectors.
+ *
+ * When connectionId changes, the button will automatically update the existing
+ * connector instance with the new connection details. If you need to force a
+ * complete remount instead, set forceRemountOnConnectionChange to true.
+ */
 export const QuilttButton = <T extends ElementType = 'button'>({
   as,
   connectorId,
   connectionId,
   institution,
+  forceRemountOnConnectionChange = false,
   onEvent,
   onOpen,
   onLoad,
@@ -44,6 +62,46 @@ export const QuilttButton = <T extends ElementType = 'button'>({
   children,
   ...props
 }: QuilttButtonProps<T> & PropsOf<T>) => {
+  // Keep track of previous connectionId for change detection
+  const prevConnectionIdRef = useRef<string | undefined>(connectionId)
+  const prevCallbacksRef = useRef({
+    onEvent,
+    onOpen,
+    onLoad,
+    onExit,
+    onExitSuccess,
+    onExitAbort,
+    onExitError,
+  })
+
+  // Track if callbacks have changed to help with debugging
+  const currentCallbacks = {
+    onEvent,
+    onOpen,
+    onLoad,
+    onExit,
+    onExitSuccess,
+    onExitAbort,
+    onExitError,
+  }
+
+  const callbacksChanged = !isDeepEqual(prevCallbacksRef.current, currentCallbacks)
+
+  useEffect(() => {
+    prevCallbacksRef.current = currentCallbacks
+  })
+
+  // Warning for potential callback reference issues
+  useEffect(() => {
+    if (callbacksChanged && prevConnectionIdRef.current !== undefined) {
+      console.warn(
+        '[Quiltt] Callback functions changed after initial render. ' +
+          'This may cause unexpected behavior. Consider memoizing callback functions ' +
+          'with useCallback to maintain stable references.'
+      )
+    }
+  }, [callbacksChanged])
+
   const { open } = useQuilttConnector(connectorId, {
     connectionId,
     institution,
@@ -57,6 +115,11 @@ export const QuilttButton = <T extends ElementType = 'button'>({
     onExitError,
   })
 
+  // Update previous connectionId reference
+  useEffect(() => {
+    prevConnectionIdRef.current = connectionId
+  }, [connectionId])
+
   const Button = as || 'button'
 
   const handleClick = (event: MouseEvent<HTMLElement>) => {
@@ -70,8 +133,21 @@ export const QuilttButton = <T extends ElementType = 'button'>({
     open()
   }
 
+  // Generate key for forced remounting if enabled, but respect user-provided key
+  const buttonKey =
+    props.key ??
+    (forceRemountOnConnectionChange
+      ? `${connectorId}-${connectionId || 'no-connection'}`
+      : undefined)
+
   return (
-    <Button onClick={handleClick} onLoad={onHtmlLoad} quiltt-connection={connectionId} {...props}>
+    <Button
+      key={buttonKey}
+      onClick={handleClick}
+      onLoad={onHtmlLoad}
+      quiltt-connection={connectionId}
+      {...props}
+    >
       {children}
     </Button>
   )

package/src/components/QuilttContainer.tsx

@@ -1,26 +1,40 @@
+import { useEffect, useRef } from 'react'
 import type { ElementType, PropsWithChildren } from 'react'
 
 import type { ConnectorSDKCallbacks } from '@quiltt/core'
 
 import { useQuilttConnector } from '@/hooks/useQuilttConnector'
 import type { PropsOf } from '@/types'
+import { isDeepEqual } from '@/utils/isDeepEqual'
 
 type QuilttContainerProps<T extends ElementType> = PropsWithChildren<
   {
     as?: T
     connectorId: string
     connectionId?: string // For Reconnect Mode
+
+    /**
+     * Forces complete remount when connectionId changes.
+     * Useful as a fallback for ensuring clean state.
+     * @default false
+     */
+    forceRemountOnConnectionChange?: boolean
   } & ConnectorSDKCallbacks
 >
 
 /**
  * QuilttContainer uses globally shared callbacks. It's recommended you only use
  * one Container at a time.
+ *
+ * When connectionId changes, the container will automatically update the existing
+ * connector instance with the new connection details. If you need to force a
+ * complete remount instead, set forceRemountOnConnectionChange to true.
  */
 export const QuilttContainer = <T extends ElementType = 'div'>({
   as,
   connectorId,
   connectionId,
+  forceRemountOnConnectionChange = false,
   onEvent,
   onLoad,
   onExit,
@@ -30,7 +44,46 @@ export const QuilttContainer = <T extends ElementType = 'div'>({
   children,
   ...props
 }: QuilttContainerProps<T> & PropsOf<T>) => {
+  // Keep track of previous connectionId for change detection
+  const prevConnectionIdRef = useRef<string | undefined>(connectionId)
+  const prevCallbacksRef = useRef({
+    onEvent,
+    onLoad,
+    onExit,
+    onExitSuccess,
+    onExitAbort,
+    onExitError,
+  })
+
+  // Track if callbacks have changed to help with debugging
+  const currentCallbacks = {
+    onEvent,
+    onLoad,
+    onExit,
+    onExitSuccess,
+    onExitAbort,
+    onExitError,
+  }
+
+  const callbacksChanged = !isDeepEqual(prevCallbacksRef.current, currentCallbacks)
+
+  useEffect(() => {
+    prevCallbacksRef.current = currentCallbacks
+  })
+
+  // Warning for potential callback reference issues
+  useEffect(() => {
+    if (callbacksChanged && prevConnectionIdRef.current !== undefined) {
+      console.warn(
+        '[Quiltt] Callback functions changed after initial render. ' +
+          'This may cause unexpected behavior. Consider memoizing callback functions ' +
+          'with useCallback to maintain stable references.'
+      )
+    }
+  }, [callbacksChanged])
+
   useQuilttConnector(connectorId, {
+    connectionId,
     nonce: props?.nonce, // Pass nonce for script loading if needed
     onEvent,
     onLoad,
@@ -40,10 +93,27 @@ export const QuilttContainer = <T extends ElementType = 'div'>({
     onExitError,
   })
 
+  // Update previous connectionId reference
+  useEffect(() => {
+    prevConnectionIdRef.current = connectionId
+  }, [connectionId])
+
   const Container = as || 'div'
 
+  // Generate key for forced remounting if enabled, but respect user-provided key
+  const containerKey =
+    props.key ??
+    (forceRemountOnConnectionChange
+      ? `${connectorId}-${connectionId || 'no-connection'}`
+      : undefined)
+
   return (
-    <Container quiltt-container={connectorId} quiltt-connection={connectionId} {...props}>
+    <Container
+      key={containerKey}
+      quiltt-container={connectorId}
+      quiltt-connection={connectionId}
+      {...props}
+    >
       {children}
     </Container>
   )

package/src/hooks/useQuilttConnector.ts

@@ -1,6 +1,6 @@
 'use client'
 
-import { useCallback, useEffect, useState } from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
 
 import { cdnBase } from '@quiltt/core'
 import type {
@@ -22,29 +22,67 @@ export const useQuilttConnector = (
   const status = useScript(`${cdnBase}/v1/connector.js?agent=react-${version}`, {
     nonce: options?.nonce,
   })
-  const { session } = useQuilttSession()
+
+  // This ensures we're not destructuring `session` before the script has loaded
+  const useQuilttSessionReturn = useQuilttSession()
+  const session = useQuilttSessionReturn?.session || null
+
   const [connector, setConnector] = useState<ConnectorSDKConnector>()
   const [isOpening, setIsOpening] = useState<boolean>(false)
 
+  // Keep track of the previous connectionId to detect changes
+  const prevConnectionIdRef = useRef<string | undefined>(options?.connectionId)
+  const prevConnectorIdRef = useRef<string | undefined>(connectorId)
+  const connectorCreatedRef = useRef<boolean>(false)
+
   // Set Session
-  // biome-ignore lint/correctness/useExhaustiveDependencies: We also need to update on status change
   useEffect(() => {
     if (typeof Quiltt === 'undefined') return
+    console.debug('[Quiltt] script status: ', status)
 
     Quiltt.authenticate(session?.token)
   }, [status, session?.token])
 
   // Set Connector
-  // biome-ignore lint/correctness/useExhaustiveDependencies: We also need to update on status change
   useEffect(() => {
     if (typeof Quiltt === 'undefined' || !connectorId) return
+    console.debug('[Quiltt] script status: ', status)
 
-    if (options?.connectionId) {
-      setConnector(Quiltt.reconnect(connectorId, { connectionId: options.connectionId }))
-    } else {
-      setConnector(Quiltt.connect(connectorId, { institution: options?.institution }))
+    const currentConnectionId = options?.connectionId
+    const currentInstitution = options?.institution
+
+    // Check if this is a connectionId change on the same connector
+    const connectionIdChanged = prevConnectionIdRef.current !== currentConnectionId
+    const connectorIdChanged = prevConnectorIdRef.current !== connectorId
+
+    // If only connectionId changed (not the connectorId), the core SDK should handle this
+    // via the updated Handler.updateOptions method, so we don't need to recreate the connector
+    if (connectionIdChanged && !connectorIdChanged && connectorCreatedRef.current) {
+      // The SDK will automatically update the existing handler with new connectionId
+      // via the DocumentObserver -> Engine.onChange -> Handler.updateOptions flow
+      console.debug('[Quiltt] connectionId changed, SDK will handle update automatically')
+
+      // Update our refs
+      prevConnectionIdRef.current = currentConnectionId
+      return
     }
-  }, [status, connectorId, options?.connectionId, options?.institution])
+
+    // Only create new connector if we haven't created one yet or if connectorId changed
+    if (!connectorCreatedRef.current || connectorIdChanged) {
+      // Create new connector (initial mount or connectorId changed)
+      if (currentConnectionId) {
+        setConnector(Quiltt.reconnect(connectorId, { connectionId: currentConnectionId }))
+      } else {
+        setConnector(Quiltt.connect(connectorId, { institution: currentInstitution }))
+      }
+
+      connectorCreatedRef.current = true
+    }
+
+    // Update refs
+    prevConnectionIdRef.current = currentConnectionId
+    prevConnectorIdRef.current = connectorId
+  }, [connectorId, options?.connectionId, options?.institution, status])
 
   // onEvent
   useEffect(() => {

package/src/hooks/useQuilttInstitutions.ts

@@ -0,0 +1,124 @@
+'use client'
+
+import { useCallback, useEffect, useMemo, useState } from 'react'
+
+import { useDebounce } from 'use-debounce'
+
+import { InstitutionsAPI } from '@quiltt/core'
+import type { ErrorData, InstitutionsData } from '@quiltt/core'
+
+import { version } from '@/version'
+import useSession from './useSession'
+
+export type UseQuilttInstitutions = (
+  connectorId: string,
+  onErrorCallback?: (msg: string) => void
+) => {
+  searchTerm: string
+  searchResults: InstitutionsData
+  isSearching: boolean
+  setSearchTerm: (term: string) => void
+}
+
+export const useQuilttInstitutions: UseQuilttInstitutions = (connectorId, onErrorCallback) => {
+  const agent = useMemo(() => {
+    // Try deprecated navigator.product first (still used in some RN versions)
+    if (typeof navigator !== 'undefined' && navigator.product === 'ReactNative') {
+      return `react-native-${version}`
+    }
+
+    // Detect React Native by its unique environment characteristics
+    const isReactNative = !!(
+      // Has window (unlike Node.js)
+      (
+        typeof window !== 'undefined' &&
+        // No document in window (unlike browsers)
+        typeof window.document === 'undefined' &&
+        // Has navigator (unlike Node.js)
+        typeof navigator !== 'undefined'
+      )
+    )
+
+    return isReactNative ? `react-native-${version}` : `react-${version}`
+  }, [])
+
+  const institutionsAPI = useMemo(
+    () => new InstitutionsAPI(connectorId, agent),
+    [connectorId, agent]
+  )
+  const [session] = useSession()
+
+  const [searchTermInput, setSearchTermInput] = useState('')
+  const [searchTerm] = useDebounce(searchTermInput, 350)
+  const [searchResults, setSearchResults] = useState<InstitutionsData>([])
+
+  const [isSearching, setIsSearching] = useState(false)
+
+  /**
+   * Start Search
+   * This function is used to initiate a search for institutions based on the provided term with
+   * a minimum length of 2 characters. Debouncing is applied to avoid excessive API calls.
+   */
+  const startSearch = useCallback((term: string) => {
+    if (term.trim().length < 2) {
+      setSearchResults([])
+      setIsSearching(false)
+      return
+    }
+
+    setIsSearching(true)
+    setSearchTermInput(term)
+  }, [])
+
+  const handleError = useCallback(
+    (message: string) => {
+      const errorMessage = message || 'Unknown error occurred while searching institutions'
+
+      console.error('Quiltt Institutions Search Error:', errorMessage)
+      if (onErrorCallback) onErrorCallback(errorMessage)
+    },
+    [onErrorCallback]
+  )
+
+  /**
+   * Run Search
+   * This effect will run when the searchTerm changes and is at least 2 characters long.
+   */
+  useEffect(() => {
+    if (!session?.token || !connectorId || !searchTerm || searchTerm.trim().length < 2) {
+      return
+    }
+
+    const abortController = new AbortController()
+
+    institutionsAPI
+      .search(session?.token, connectorId, searchTerm, abortController.signal)
+      .then((response) => {
+        if (!abortController.signal.aborted) {
+          if (response.status === 200) {
+            setSearchResults(response.data as InstitutionsData)
+          } else {
+            handleError((response.data as ErrorData).message || 'Failed to fetch institutions')
+          }
+          setIsSearching(false)
+        }
+      })
+      .catch((error) => {
+        if (!abortController.signal.aborted) {
+          handleError(error.message)
+          setIsSearching(false)
+        }
+      })
+
+    return () => abortController.abort()
+  }, [session?.token, connectorId, searchTerm, institutionsAPI, handleError])
+
+  return {
+    searchTerm,
+    searchResults,
+    isSearching,
+    setSearchTerm: startSearch,
+  }
+}
+
+export default useQuilttInstitutions