From 3fb2aff3dd9ac06b32050f4e24212ec70c067e0d Mon Sep 17 00:00:00 2001
From: Lotfi Arif <52082662+Lotfi-Arif@users.noreply.github.com>
Date: Tue, 16 Jun 2026 10:29:32 +0200
Subject: [PATCH] docs(react-web-sdk): enhance README with usage examples for
 useOptimization hook

Added detailed examples demonstrating the use of the `useOptimization()` hook, including best practices for maintaining SDK instance binding and avoiding destructuring of SDK methods. This improves clarity for developers integrating the SDK into their React components.
---
 .../web/frameworks/react-web-sdk/README.md    | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/packages/web/frameworks/react-web-sdk/README.md b/packages/web/frameworks/react-web-sdk/README.md
index 77e00f68..d2ab307b 100644
--- a/packages/web/frameworks/react-web-sdk/README.md
+++ b/packages/web/frameworks/react-web-sdk/README.md
@@ -179,6 +179,25 @@ Use `useOptimization()` when a component needs direct access to the instance for
 `identify()`, `reset()`, or manual tracking. Use `useEntryResolver()` when a component needs manual
 entry resolution without the `OptimizedEntry` wrapper:
 
+`useOptimization()` returns the SDK instance itself. Keep that instance in a variable and call
+methods from it. Do not destructure SDK methods from the returned value because those methods rely
+on the instance `this` binding.
+
+```tsx
+import { useOptimization } from '@contentful/optimization-react-web'
+
+function ProductCta() {
+  const optimization = useOptimization()
+
+  return <button onClick={() => optimization.track({ event: 'purchase' })}>Buy now</button>
+}
+```
+
+```tsx
+// Avoid destructuring SDK methods; this loses the instance binding.
+const { track } = useOptimization()
+```
+
 ```tsx
 import { useEntryResolver } from '@contentful/optimization-react-web'