perf(useIsMacOS): replace useState+useEffect with useSyncExternalStore

[hectahertz]

Closes #

useIsMacOS used useState + useEffect to detect the platform in an SSR-safe way. The useState initializer already computed the correct value on the client, but the useEffect unconditionally called setIsMacOS with the same value, scheduling a second render pass on every mount.

Replaced with useSyncExternalStore, the idiomatic React 18+ API for values that differ between server and client. During hydration, React handles the server/client mismatch internally in a single synchronous pass, no extra render needed.

Eliminates a guaranteed double-render on every mount for all consumers: Tooltip, KeybindingHint, and TreeView. The impact scales with the number of children, since the unnecessary re-render cascades to all of them.

Measurements

Measured on the TreeView stress test (1000 tree items) as worst case. 2 runs each, reload-based traces, no CPU/network throttling.

Metric	Before (main)	After (PR)	Delta
✨ LCP (median) ✨	2,416ms	2,264ms	-152ms (-6.3%)
Render Delay (median)	2,216ms	2,095ms	-121ms (-5.5%)

Individual runs

Before (main):

• Run 1: LCP 2,421ms (TTFB 206ms, Render Delay 2,215ms)
• Run 2: LCP 2,410ms (TTFB 192ms, Render Delay 2,217ms)

After (PR):

• Run 1: LCP 2,268ms (TTFB 155ms, Render Delay 2,113ms)
• Run 2: LCP 2,259ms (TTFB 182ms, Render Delay 2,077ms)

TreeView shows the largest improvement because a single useIsMacOS call at the root triggers a re-render that cascades across 1000 child items. Tooltip and KeybindingHint will see smaller absolute gains but every instance still saves one full render cycle on mount.

Changelog

New

N/A

Changed

• useIsMacOS now uses useSyncExternalStore instead of useState + useEffect, eliminating an unnecessary re-render on every mount

Removed

N/A

Rollout strategy

• Patch release
• Minor release
• Major release; if selected, include a written rollout or migration plan
• None; if selected, include a brief description as to why

Testing & Reviewing

All 3 consumer test suites pass (89 tests total):

• TooltipV2/__tests__/Tooltip.test.tsx
• KeybindingHint/KeybindingHint.test.tsx
• TreeView/TreeView.test.tsx

To verify the double render is eliminated:

1. Add a console.log('render') inside the Tooltip component
2. Render a Tooltip in a test/story
3. Before: logs "render" twice on mount
4. After: logs "render" once

Merge checklist

• Added/updated tests
• Added/updated documentation
• Added/updated previews (Storybook)
• Changes are SSR compatible
• Tested in Chrome
• Tested in Firefox
• Tested in Safari
• Tested in Edge
• (GitHub staff only) Integration tests pass at github/github (Learn more about how to run integration tests)

[changeset-bot]

🦋 Changeset detected

Latest commit: 3b97134

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/react	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

👋 Hi, this pull request contains changes to the source code that github/github-ui depends on. If you are GitHub staff, test these changes with github/github-ui using the integration workflow. Or, apply the integration-tests: skipped manually label to skip these checks.

[Copilot]

Pull request overview

This PR optimizes the SSR-safe useIsMacOS hook by switching it to React 18’s useSyncExternalStore, removing an unconditional mount-time state update that caused an extra render pass in all consumers (e.g. Tooltip, KeybindingHint, TreeView).

Changes:

• Replaced useState + useEffect in useIsMacOS with useSyncExternalStore to avoid a guaranteed second render on mount.
• Added a changeset for a patch release describing the performance improvement.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
packages/react/src/hooks/useIsMacOS.ts	Refactors platform detection to useSyncExternalStore to avoid unnecessary mount re-renders while staying SSR-safe.
.changeset/perf-useismacOS-sync-external-store.md	Adds a patch changeset documenting the perf change for release notes.

[Copilot]

useIsMacOS is a publicly exported hook and its behavior around SSR/hydration is subtle. There are hook unit tests for other hooks under packages/react/src/hooks/__tests__, but none for this one—please add a small useIsMacOS test that at least verifies SSR defaults to false (e.g. via react-dom/server), and client behavior can be controlled via a mocked @primer/behaviors/utils implementation.

[primer-integration]

👋 Hi from github/github-ui! Your integration PR is ready: https://github.com/github/github-ui/pull/13848

[primer-integration]

Integration test results from github/github-ui:

  CI Passed
  VRT Waiting
  Projects Passed