fix(ui): improve search page UX

[ShroXd]

🔗 Linked issue

Resolves#2112

🧭 Context

As the linked issue mentioned, the search page layout shifts too much during typing, which is not a good user experience.

📚 Description

Several UX improvements to the search page.

1. Add debounce to searching, the delay is 250ms, same value as updateUrlQuery.
2. Tweak transition animation binding on the element to prevent flicker during searching.
3. Improve calculation logic of showClaimPrompt to make the behavior more intuitive.
4. Add transition to suggestion area to improve the user experience.

Screen.Recording.2026-03-17.at.14.24.18.mov

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs.npmx.dev	Ready	Preview, Comment	Mar 23, 2026 11:19pm
npmx.dev	Ready	Preview, Comment	Mar 23, 2026 11:19pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
npmx-lunaria	Ignored		Mar 23, 2026 11:19pm

[codecov]

Codecov Report

❌ Patch coverage is 50.00000% with 3 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
app/composables/useGlobalSearch.ts	50.00%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b842e994-6a6b-4968-8832-6900d25cbf92

📥 Commits

Reviewing files that changed from the base of the PR and between 5e80824 and 27b0461.

📒 Files selected for processing (1)

• app/pages/search.vue

🚧 Files skipped from review as they are similar to previous changes (1)

• app/pages/search.vue

---

📝 Walkthrough

Walkthrough

This PR adds a reactive newSearchBatchSize threshold to Package List rendering to limit which items receive staggered enter animations (items with index >= newSearchBatchSize), resets that threshold when a new search result set arrives, and adjusts per-item animation delays accordingly. In useGlobalSearch.ts it introduces SEARCH_DEBOUNCE_MS (100ms), a debounced commitSearchQuery with cancel/flush integration, and uses it for instantSearch and URL-update debouncing. In search.vue the showClaimPrompt computed is refactored with early returns, suggestion lists are wrapped in Transition, and the claim button gains disabled handling during pending status.

Possibly related PRs

• feat: show package claim for not connected users #1514: Modifies the same claim-prompt rendering and showClaimPrompt logic in app/pages/search.vue.
• perf: search improvements #1431: Adjusts useGlobalSearch.ts debounce/flush behaviour and committing of search queries.
• fix: missed input parts on quick search #1394: Touches global search state and input debouncing used by the search composables.

Suggested reviewers

• danielroe

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description check	✅ Passed	The pull request description clearly relates to the changeset, describing UX improvements to the search page including debounce, animation tweaks, claim prompt logic, and transition effects.
Linked Issues check	✅ Passed	The PR addresses the core issue #2112 by preventing layout shifts through conditional animation binding and debouncing, and improves claim prompt logic stability.
Out of Scope Changes check	✅ Passed	All code changes are scoped to search-related functionality and directly address the layout-shift issue and UX improvements mentioned in issue #2112.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

app/components/Package/List.vue (1)

122-133: ⚠️ Potential issue | 🟠 Major

Handle empty→non-empty results as a new-search reset.

At Line 129, the reset condition skips the oldResults.length === 0 && newResults.length > 0 transition. That leaves newSearchBatchSize stale (often Infinity or 0) and breaks the intended animation split for subsequent appended items.

💡 Proposed fix

 watch(
() => props.results,
(newResults, oldResults) => {
// If this looks like a new search (different first item or much shorter), reset
if (
!oldResults ||
+ oldResults.length === 0 ||
newResults.length === 0 ||
- (oldResults.length > 0 && newResults[0]?.package.name !== oldResults[0]?.package.name)+ newResults[0]?.package.name !== oldResults[0]?.package.name
) {
hasScrolledToInitial.value = false
newSearchBatchSize.value = newResults.length
}
},
)

🧹 Nitpick comments (1)

app/components/Package/List.vue (1)

182-190: Consider extracting the repeated animation binding into a helper.

The same :class/:style animation logic is duplicated in both card branches. A small helper/computed would reduce drift risk when tuning animation behaviour later.

Also applies to: 241-249

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3beedd05-2a22-4856-a16f-47aed15ba65e

📥 Commits

Reviewing files that changed from the base of the PR and between 8ee186a and 1e89802.

📒 Files selected for processing (3)

• app/components/Package/List.vue
• app/composables/useGlobalSearch.ts
• app/pages/search.vue

[pauliecodes]

Tested this locally and the search debounce and the layout shift fixes for the Claim button work really well. LGTM!

[MatteoGabriele]

I think it might be more effective to fix this with a different UI rather than using a complex debounce system. I can really feel the lag compared to our current setup, and since we prioritize speed, it might be worth approaching this from a different perspective.

@alexdln shared the Figma file yesterday, and I noticed a different layout on most pages: maybe moving the package claim and the owner to the column is the right move here. What do you think?

[alexdln]

If this works, it will be useful in any case, since on the sidebar in the future there may be 2 and more cards - f.e. user and organization

(but sorry, I'm not sure I understand the solution and can't properly review it, but result lgtm)

[ShroXd]

@MatteoGabriele Thanks for pointing it out. Actually, the major part of this fix is the conditional transition animation on the list, not the debounce. I added the debounce to make the deletion experience better — when users delete characters by pressing keys quickly, without debounce the list would change immediately and cause a flickering effect. If the lag feels too noticeable, I've reduced SEARCH_DEBOUNCE_MS to 100ms in the latest commit — feel free to give it a try and let me know how it feels!

On the other hand, the new layout looks awesome! However, on small-screen devices, a one-column layout is the only option, which brings us back to the original problem of handling the flickering suggestions area. So I think it's still necessary to do something to improve it.

@alexdln Thanks for reviewing. Could you point out which part of the code is confusing to you? It might be a good signal for me to improve the implementation or add some comments to explain it.

[nicolo-ribaudo]

I added the debounce to make the deletion experience better — when users delete characters by pressing keys quickly, without debounce the list would change immediately and cause a flickering effect.

Could we debounce only when the new query is shorter than the previous one?

[MatteoGabriele]

@ShroXd Thanks for the updates; it does feel just as fast now. This is a visual improvement, and I think we should add it. My overall impression is that this is a temporary fix, and the real issue lies in our design: I believe these two elements, the user badge and the claim badge, should be positioned where they can appear and disappear without causing the page to shift constantly.
I think we should create an issue and reconsider it, perhaps aligning with the design on Figma.

[ShroXd]

Could we debounce only when the new query is shorter than the previous one?

We can do it, but the current debounce implementation wraps the entire block as debounce(() => { ... }), which makes conditional debouncing complex and hard to understand. Considering @MatteoGabriele's comment above, I think we could improve this from a design perspective rather than adding complex code.

[ShroXd]

@ShroXd Thanks for the updates; it does feel just as fast now. This is a visual improvement, and I think we should add it. My overall impression is that this is a temporary fix, and the real issue lies in our design: I believe these two elements, the user badge and the claim badge, should be positioned where they can appear and disappear without causing the page to shift constantly. I think we should create an issue and reconsider it, perhaps aligning with the design on Figma.

Agree, an improved design could avoid a lot of complex processing like in this PR.

I think there is a related topic: debounce. Many of us use it to make the page look smooth, but as you experienced, a 200ms debounce makes the search feel laggy. Maybe we could also discuss whether we should use debounce at all, and if so, what the standard should be. 🤔

[ghostdevv]

@ShroXd Thanks for the updates; it does feel just as fast now. This is a visual improvement, and I think we should add it. My overall impression is that this is a temporary fix, and the real issue lies in our design: I believe these two elements, the user badge and the claim badge, should be positioned where they can appear and disappear without causing the page to shift constantly. I think we should create an issue and reconsider it, perhaps aligning with the design on Figma.

Do you mean that we shouldn't merge this? Or we should merge this but it's just a temporary fix until we update the design?

[alex-key]

@ShroXd Thanks for the updates; it does feel just as fast now. This is a visual improvement, and I think we should add it. My overall impression is that this is a temporary fix, and the real issue lies in our design: I believe these two elements, the user badge and the claim badge, should be positioned where they can appear and disappear without causing the page to shift constantly. I think we should create an issue and reconsider it, perhaps aligning with the design on Figma.

Agree 100%

Also replying to "However, on small-screen devices, a one-column layout is the only option, which brings us back to the original problem of handling the flickering suggestions area. So I think it's still necessary to do something to improve it." by @ShroXd :
I think it still could be done w/o layout shifts by adding floating buttons on the bottom of the screen or similar.

This flicking user/claim tiles are really annoying to me. Especially considering that user would click "Claim" maybe 1 or 2 times during the whole period of npmx usage and most of users never clicks it at all

[ShroXd]

@alex-key That's a good point! The flickering screen bothers me too. We can merge it for now — even if it's just a temporary fix — and revisit the design later.

[alex-key]

@alex-key That's a good point! The flickering screen bothers me too. We can merge it for now — even if it's just a temporary fix — and revisit the design later.

Absolutely. I am sure one of maintainers will approve it soon!