[Onyx Audit] useOnyx is expensive (especially on list items)

[fabioh8010]

Overview

This issue is part of our current effort to audit the performance and scalability of Onyx.

During the Step 1: Objective Analysis we gathered a list of Perceived Problems we have exclusively about Onyx, that is, the problems in Onyx we imagine or have some evidences that that are pain points / performance bottenecks to Onyx, but we need more analysis to confirm if they really are and, if so, how much of a problem they are currently.

The main goal right now is to deep dive into each Perceived Problem, investigate/audit it and come up with findings, which we will use for the next discussions.

Problem

There are performance improvements every time we decide to remove useOnyx calls from list items and/or lift up the state. Here are some proposals/discussions that show this:

• Eliminate redundant data operations in EReceipt component
• Discussion about connecting to collections in list items
• Reduce useOnyx calls on list-item level in TransactionItemRowRBRWithOnyx
• Avoid calling useOnyx from within LHN list items

While these kind of solutions make our App faster, they also end up not addressing the root cause of the issue: useOnyx calls are too expensive to be used inside list items.

useOnyx should be extremely fast to the point we can just pass entity IDs to our components and use them to hook into Onyx state, without having a performance hit. Removing useOnyx and lifting up the state solves the problem temporarily but it will continue to limit our application and nudge us into worse code and bad practices.

I think Rory's proposal it's the right direction for this topic: Audit useOnyx and determine why it's expensive to call on list items.

We have been working on several improvements on useOnyx e.g. selector memoization and getSnapshot caching that will greatly benefit this part, but looks like there are still more we can do about this.

Action Items

1. Audit useOnyx and determine why it's expensive to call on list items.
2. Furthermore, audit useOnyx to check if we have more performance bottlenecks there, not exclusively related to list items.

Relevant Links

Step 1 Canvas: https://expensify.slack.com/docs/T02P6RS2ZK7/F09B668M1MG

Slack thread: https://expensify.slack.com/archives/C05LX9D6E07/p1757416459028329

[blazejkustra]

Hey! I’m Błażej Kustra from Software Mansion, an expert agency, and I’d like to work on this issue!

[blazejkustra]

No updates yet, I've been busy with other tasks. Will look into this early next week

[blazejkustra]

I'm starting investigation today, will post updates here 👀

[blazejkustra]

Got a bit sidetracked with a different issue. I'll share an update tomorrow on Monday 😢.

[blazejkustra]

Update (finally) 🚀

Goal: Audit useOnyx and determine why it’s expensive to call on list items.

I started with that goal and explored multiple possible reasons for why useOnyx might be slow. Below are my findings.

1. ❌ Double render on mount

On initial mount, if the requested key’s data isn’t in memory, useOnyx first returns [undefined, {status: 'loading'}], then updates to {status: 'loaded'} once the data arrives, causing the component to render twice.

While this is technically true, it’s not a real issue in practice. Onyx’s in-memory cache ensures that useOnyx usually returns the value immediately during the first render. After some consideration, I believe this behavior is expected and acceptable, it’s how asynchronous global storage would naturally work.

2. ❌ Each useOnyx opens its own connection

This also turned out not to be an issue. Connections are correctly reused under the hood thanks to ConnectionManager.

3. ❌ Selectors re-render even if the returned data hasn’t changed

Verified this as well, selectors currently work as intended and do not cause unnecessary re-renders.

4. ✅ Selectors aren’t memoized or reused

Even though selectors behave correctly, heavy selector computations are recalculated every time data changes, which can lead to wasted CPU time.

I haven’t measured the impact yet since I didn’t implement memoized selectors, but this will likely be addressed in Onyx 2.0 & we would implement internal derived value system in Onyx v2.

For future work, using memoization helpers like reselect or re-reselect would be a strong improvement.

5. ✅ useOnyx wrapper in E/App adds overhead

Recent changes significantly improved the performance of the E/App useOnyx wrapper by avoiding unnecessary search computations and re-renders.

Tt still introduces measurable overhead for all useOnyx calls used on the Search page. I didn’t dig deep into this since there’s an ongoing effort to remove snapshots entirely, which will likely deprecate this wrapper.

6. ✅ useOnyx is overly complex and has too many responsibilities

This is the main issue. The internal logic of useOnyx is extremely heavy, over 25 React hooks doing a variety of things.

To get perspective, I compared our implementation to other state libraries:

Library	Hooks used	Notes
Redux useSelector	~4	Logic mostly delegated elsewhere
Zustand	~3	Very small, relies on useSyncExternalStore
Legend-State	~2–3	Extremely optimized for performance 🏎️

Compared to these, our useOnyx is bloated. Much of that complexity comes from preserving feature parity with withOnyx. It does far more than it should. Instead of being a simple “subscribe to store” hook, it’s responsible for:

1. Managing selectors
2. Handling loading state
3. Subscribing directly to storage and cache layers
4. Managing key eviction logic
5. Doing its own value comparison
6. Potentially more...

All of these should ideally live outside the hook. useOnyx should just listen to the store, not orchestrate everything around it. My takeaway: we need to slim it down dramatically.

[blazejkustra]

🧪 Benchmark

To get actual numbers, I measured how many useOnyx hooks are mounted when opening a single chat, around 3,000 on my account (I used this in the actual benchmark by mounting 3k useOnyx).

I then built a benchmark using React’s profiling tools to compare:

• the current useOnyx (~25 hooks)
• a simplified version (~3 hooks)

Original useOnyx (~25 hooks)

Average mount time: 21 ms
Average update time: 1.1 ms

Sample benchmark

25.mov

Simplified implementation (~3 hooks)

Average mount time: 12 ms
Average update time: 0.6 ms

Sample benchmark

3.mov

Results

👉 The simplified version is roughly twice as fast, a 100% speedup in both mount and update time. You can see the benchmark code and run it yourself here.

Summary

The real bottleneck isn’t any single bug. It’s that useOnyx has grown into a do-everything hook. Other state libraries (Zustand, Legend-State, Redux) show that subscription hooks can stay simple, relying on the store layer for heavy logic.

A future direction could be to refactor useOnyx into a thin wrapper around useSyncExternalStore, leaving selectors, eviction, and cache logic to separate utilities outside of react lifecycle.

[blazejkustra]

7. ✅ Architectural mismatch: useOnyx(key) subscribes by key, not by store/observable

While comparing with other state libraries like Zustand and Legend-State, I noticed a fundamental architectural difference that might be limiting useOnyx performance and simplicity.

In libraries such as:

• Legend-State, components subscribe to observables (e.g. use$(observable)), not raw keys.
• Zustand, components subscribe to a store via useStore(selector). One global store manages state, and components only read slices, reducing the number of listeners.

In both cases, the subscription target is stable and the subscription logic inside the hook stays constant. The hook just listens to that object and re-renders when it changes.

In contrast, Onyx’s API subscribes directly to a key string and does bunch of operations:

const [user] = useOnyx(ONYXKEYS.USER);

Although ConnectionManager helps with reusing these connections a bunch of calculations are necessary in each useOnyx.

Proposal

We could consider evolving the API to separate subscription creation from data consumption. Similar to how Zustand or Legend-State work. For example:

// New conceptual API
const userSub = OnyxSub(ONYXKEYS.USER);
const [user] = useOnyx(userSub);

This would:

• Create one shared subscription per key instead of per hook instance.
• Let us manage memoization, caching, and connection reuse at the store level.
• Simplify useOnyx itself, it would just subscribe to an existing observable rather than managing connection setup each time.

Such an architectural change could drastically reduce repeated subscription work, simplify the hook’s logic, and align useOnyx with modern state management patterns.

[roryabraham]

On initial mount, if the requested key’s data isn’t in memory, useOnyx first returns [undefined, {status: 'loading'}], then updates to {status: 'loaded'} once the data arrives ... After some consideration, I believe this behavior is expected and acceptable, it’s how asynchronous global storage would naturally work

Just trying to brainstorm here, but perhaps a natural improvement to this would be to:

1. wrap the initial data read in a Promise
2. use the promise using React's use API

That way, useOnyx can continue to function as it currently does when not wrapped in a Suspense boundary. But if wrapped in a Suspense boundary, it would suspend the component that's using it and allow React to concurrently render a loading indicator if necessary. This is a modern React practice that leads to better performance and UX than using traditional synchronous re-renders for loading states.