From 2aab94599e48165f524f8e79cc93b310b6a9c95e Mon Sep 17 00:00:00 2001
From: Noitidart <noitidart@protonmail.com>
Date: Mon, 13 Jul 2026 21:56:24 -0700
Subject: [PATCH] Note that screenLayout is called as a function, not a
 component

---
 versioned_docs/version-7.x/group.md     | 20 ++++++++++++++++++++
 versioned_docs/version-7.x/navigator.md | 20 ++++++++++++++++++++
 versioned_docs/version-8.x/group.md     | 20 ++++++++++++++++++++
 versioned_docs/version-8.x/navigator.md | 20 ++++++++++++++++++++
 4 files changed, 80 insertions(+)

diff --git a/versioned_docs/version-7.x/group.md b/versioned_docs/version-7.x/group.md
index 1ff642c138..8772cb4834 100644
--- a/versioned_docs/version-7.x/group.md
+++ b/versioned_docs/version-7.x/group.md
@@ -287,6 +287,26 @@ const MyStack = createNativeStackNavigator({
 </TabItem>
 </ConfigTabs>
 
+:::warning
+
+The function passed to `screenLayout` is invoked as a regular function, not rendered as a React component. This means you **cannot call React Hooks directly inside it** — doing so will fail at runtime with errors such as _"Should have a queue. You are likely calling Hooks conditionally, which is not allowed."_
+
+If you need to use Hooks, wrap your logic in a separate component and return it as JSX:
+
+```jsx
+function MyScreenLayout(props) {
+  const value = useMyHook(); // ✅ Hook runs inside a real component
+
+  return <ErrorBoundary>{props.children}</ErrorBoundary>;
+}
+
+const Stack = createNativeStackNavigator({
+  screenLayout: (props) => <MyScreenLayout {...props} />,
+});
+```
+
+:::
+
 ### Navigation key
 
 Optional key for a group of screens. If the key changes, all existing screens in this group will be removed (if used in a stack navigator) or reset (if used in a tab or drawer navigator):
diff --git a/versioned_docs/version-7.x/navigator.md b/versioned_docs/version-7.x/navigator.md
index aa39797a55..795c58f5ef 100644
--- a/versioned_docs/version-7.x/navigator.md
+++ b/versioned_docs/version-7.x/navigator.md
@@ -310,6 +310,26 @@ function MyStack() {
 </TabItem>
 </ConfigTabs>
 
+:::warning
+
+The function passed to `screenLayout` is invoked as a regular function, not rendered as a React component. This means you **cannot call React Hooks directly inside it** — doing so will fail at runtime with errors such as _"Should have a queue. You are likely calling Hooks conditionally, which is not allowed."_
+
+If you need to use Hooks, wrap your logic in a separate component and return it as JSX:
+
+```jsx
+function MyScreenLayout(props) {
+  const value = useMyHook(); // ✅ Hook runs inside a real component
+
+  return <ErrorBoundary>{props.children}</ErrorBoundary>;
+}
+
+const Stack = createNativeStackNavigator({
+  screenLayout: (props) => <MyScreenLayout {...props} />,
+});
+```
+
+:::
+
 ### Router
 
 :::warning
diff --git a/versioned_docs/version-8.x/group.md b/versioned_docs/version-8.x/group.md
index 17793f8a58..118332e8ba 100644
--- a/versioned_docs/version-8.x/group.md
+++ b/versioned_docs/version-8.x/group.md
@@ -287,6 +287,26 @@ const MyStack = createNativeStackNavigator({
 </TabItem>
 </ConfigTabs>
 
+:::warning
+
+The function passed to `screenLayout` is invoked as a regular function, not rendered as a React component. This means you **cannot call React Hooks directly inside it** — doing so will fail at runtime with errors such as _"Should have a queue. You are likely calling Hooks conditionally, which is not allowed."_
+
+If you need to use Hooks, wrap your logic in a separate component and return it as JSX:
+
+```jsx
+function MyScreenLayout(props) {
+  const value = useMyHook(); // ✅ Hook runs inside a real component
+
+  return <ErrorBoundary>{props.children}</ErrorBoundary>;
+}
+
+const Stack = createNativeStackNavigator({
+  screenLayout: (props) => <MyScreenLayout {...props} />,
+});
+```
+
+:::
+
 ### Navigation key
 
 Optional key for a group of screens. If the key changes, all existing screens in this group will be removed (if used in a stack navigator) or reset (if used in a tab or drawer navigator):
diff --git a/versioned_docs/version-8.x/navigator.md b/versioned_docs/version-8.x/navigator.md
index 4ba7a5f3f6..289a8f9053 100644
--- a/versioned_docs/version-8.x/navigator.md
+++ b/versioned_docs/version-8.x/navigator.md
@@ -270,6 +270,26 @@ function MyStack() {
 </TabItem>
 </ConfigTabs>
 
+:::warning
+
+The function passed to `screenLayout` is invoked as a regular function, not rendered as a React component. This means you **cannot call React Hooks directly inside it** — doing so will fail at runtime with errors such as _"Should have a queue. You are likely calling Hooks conditionally, which is not allowed."_
+
+If you need to use Hooks, wrap your logic in a separate component and return it as JSX:
+
+```jsx
+function MyScreenLayout(props) {
+  const value = useMyHook(); // ✅ Hook runs inside a real component
+
+  return <ErrorBoundary>{props.children}</ErrorBoundary>;
+}
+
+const Stack = createNativeStackNavigator({
+  screenLayout: (props) => <MyScreenLayout {...props} />,
+});
+```
+
+:::
+
 ### Router
 
 Routers can be customized with the `router` prop on navigator to override how navigation actions are handled.