Note that screenLayout is called as a function, not a component

[Noitidart]

Problem

The screenLayout documentation describes it as "a function that returns a React element," and all examples return JSX immediately. This is correct but implicit — a developer who needs to call a hook inside screenLayout (e.g., to read theme context, access app state, etc.) discovers only at runtime that React throws:

Should have a queue. You are likely calling Hooks conditionally, which is not allowed.

The root cause is that React Navigation invokes screenLayout via a plain function call (useDescriptors.tsx:267-275), not via JSX. Hooks called inside have no React fiber to register against. The misleading "conditionally" wording in React's error sent me searching for a conditional that didn't exist.

Solution

Add a warning block (with workaround) after the existing screenLayout examples in both navigator.md and group.md for v7 and v8. The workaround is to wrap hook logic in a real component and return it as JSX — then React mounts it properly and hooks work.

Why

I hit this myself and lost real time to it. The current examples all return JSX immediately (which sidesteps the issue), so there's no way to anticipate it from reading the docs. The error message points at conditional hook calls, but the actual problem is the function-invocation pattern — which the docs don't currently surface.

Scope

Same note added to all 4 files where the screenLayout section appears:

• versioned_docs/version-7.x/navigator.md
• versioned_docs/version-7.x/group.md
• versioned_docs/version-8.x/navigator.md
• versioned_docs/version-8.x/group.md

Marked as a :::warning rather than :::note for visual prominence — this is a real footgun, not a footnote. Existing :::warning blocks in these files (e.g., the Router section about experimental APIs) use the same styling.

Verified markdownlint-cli2 and prettier both pass on the changed files.

[netlify]

✅ Deploy Preview for react-navigation-docs ready!

Name	Link
🔨 Latest commit	2aab945
🔍 Latest deploy log	https://app.netlify.com/projects/react-navigation-docs/deploys/6a55c1931ece230008c38c22
😎 Deploy Preview	https://deploy-preview-1503--react-navigation-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.