From ba7f6bc5416ad7baf68890293197ea35fabbb838 Mon Sep 17 00:00:00 2001
From: Greg Littlefield <greg.littlefield@workiva.com>
Date: Wed, 9 Oct 2024 10:53:00 -0700
Subject: [PATCH] Recommend hooks over connect in redux docs

---
 doc/over_react_redux_documentation.md | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/doc/over_react_redux_documentation.md b/doc/over_react_redux_documentation.md
index 52d6e9eb6..3d147f9a4 100644
--- a/doc/over_react_redux_documentation.md
+++ b/doc/over_react_redux_documentation.md
@@ -10,6 +10,10 @@ A Dart wrapper for React Redux, providing targeted state updates.
   - [Running the Examples](#running-the-examples)
 - **[Using it in your project](#using-it-in-your-project)**
 - **[ReduxProvider](#reduxprovider)**
+- **[Hooks](#hooks)**
+  - [useSelector](#useselector)
+  - [useDispatch](#usedispatch)
+  - [useStore](#usestore)
 - **[Connect](#connect)**
   - [`connect` Parameters](#connect-parameters)
     - [mapStateToProps](#mapstatetoprops)
@@ -22,10 +26,6 @@ A Dart wrapper for React Redux, providing targeted state updates.
     - [context](#context)
     - [pure](#pure)
     - [forwardRef](#forwardref)
-- **[Hooks](#hooks)**
-  - [useSelector](#useselector)
-  - [useDispatch](#usedispatch)
-  - [useStore](#usestore)
 - **[Using Multiple Stores](#using-multiple-stores)**
 - **[Using Redux DevTools](#using-redux-devtools)**
   - [Integrating with DevTools](#integration-with-devtools)
@@ -168,6 +168,8 @@ A wrapper around the JS react-redux `connect` function that supports OverReact c
 
 > See: <https://react-redux.js.org/api/connect>
 
+> ![TIP] connect still works and is supported. However, we recommend using the hooks API as the default.
+
 **Example:**
 
 ```dart
@@ -299,10 +301,18 @@ class CounterProps = UiProps with CounterPropsMixin, OtherPropsMixin;
 > [More information about the `connect` function](https://react-redux.js.org/api/connect#connect)
 
 ## Hooks
+
 OverReact exposes wrappers around React Redux hook APIs, which serve as an alternative to the existing [`connect()`](#connect) Higher Order Component. 
 These APIs allow you to subscribe to the Redux store and dispatch actions, without having to wrap your components 
 in [`connect()`](#connect).
 
+> [!TIP]
+> **We recommend using the React-Redux hooks API as the default approach in your React components.**
+>
+> The existing connect API still works and will continue to be supported, but the hooks API is simpler, 
+> requires less OverReact boilerplate, and doesn't involve suppressing validation for required props 
+> (see [connect](#connect) docs for more info).
+
 > See: <https://react-redux.js.org/api/hooks>
 
 As with [`connect()`](#connect), you should start by wrapping your entire application in a