feat: make instant search optional

Author: alex-key

app/components/Compare/PackageSelector.vue

@@ -12,6 +12,7 @@ const maxPackages = computed(() => props.max ?? 4)
 
 // Input state
 const inputValue = shallowRef('')
+const committedInput = shallowRef('')
 const isInputFocused = shallowRef(false)
 
 // Keyboard navigation state
@@ -21,7 +22,20 @@ const PAGE_JUMP = 5
 
 // Use the shared search composable (supports both npm and Algolia providers)
 const { searchProvider } = useSearchProvider()
-const { data: searchData, status } = useSearch(inputValue, searchProvider, { size: 15 })
+const { settings } = useSettings()
+
+// When instantSearch is off, only search after Enter is pressed
+watch(inputValue, val => {
+  if (settings.value.instantSearch) {
+    committedInput.value = val
+  }
+
+  if (!val) {
+    committedInput.value = ''
+  }
+})
+
+const { data: searchData, status } = useSearch(committedInput, searchProvider, { size: 15 })
 
 const isSearching = computed(() => status.value === 'pending')
 
@@ -50,7 +64,9 @@ const showNoDependencyOption = computed(() => {
 
 // Filter out already selected packages
 const filteredResults = computed(() => {
-  if (!searchData.value?.objects) return []
+  // Intentionally clear results if input is empty
+  if (!committedInput.value || !searchData.value?.objects) return []
+
   return searchData.value.objects
     .map(o => ({
       name: o.package.name,
@@ -150,6 +166,12 @@ function handleKeydown(e: KeyboardEvent) {
 
       e.preventDefault()
 
+      // When instant search is off, first Enter commits the query to trigger search
+      if (!settings.value.instantSearch && committedInput.value !== inputValueTrim) {
+        committedInput.value = inputValueTrim
+        return
+      }
+
       // If an item is highlighted, select it
       if (highlightedIndex.value >= 0 && highlightedIndex.value < count) {
         addPackage(items[highlightedIndex.value]!.name)

app/components/Header/SearchBox.vue

@@ -16,10 +16,10 @@ const showSearchBar = computed(() => {
   return route.name !== 'index'
 })
 
-const { model: searchQuery, flushUpdateUrlQuery } = useGlobalSearch('header')
+const { model: searchQuery, startSearch } = useGlobalSearch('header')
 
 function handleSubmit() {
-  flushUpdateUrlQuery()
+  startSearch()
 }
 
 // Expose focus method for parent components

app/composables/useGlobalSearch.ts

@@ -5,21 +5,42 @@ import { debounce } from 'perfect-debounce'
 const pagesWithLocalFilter = new Set(['~username', 'org'])
 
 export function useGlobalSearch(place: 'header' | 'content' = 'content') {
+  const { settings } = useSettings()
   const { searchProvider } = useSearchProvider()
   const searchProviderValue = computed(() => {
     const p = normalizeSearchParam(route.query.p)
     if (p === 'npm' || searchProvider.value === 'npm') return 'npm'
     return 'algolia'
   })
+
   const router = useRouter()
   const route = useRoute()
+  // Internally used searchQuery state
   const searchQuery = useState<string>('search-query', () => {
     if (pagesWithLocalFilter.has(route.name as string)) {
       return ''
     }
     return normalizeSearchParam(route.query.q)
   })
 
+  // Committed searchQuery: last value submitted by user
+  // Syncs instantly when instant search is on VS only on Enter presswhen off
+  const committedSearchQuery = useState<string>('committed-search-query', () => {
+    if (pagesWithLocalFilter.has(route.name as string)) {
+      return ''
+    }
+    return normalizeSearchParam(route.query.q)
+  })
+
+  watch(searchQuery, val => {
+    if (settings.value.instantSearch) {
+      committedSearchQuery.value = val
+    } else if (!val) {
+      // Only clear committed query when input is cleared
+      committedSearchQuery.value = ''
+    }
+  })
+
   // clean search input when navigating away from search page
   watch(
     () => route.query.q,
@@ -29,6 +50,8 @@ export function useGlobalSearch(place: 'header' | 'content' = 'content') {
       if (!searchQuery.value) searchQuery.value = value
     },
   )
+
+  // Updates URL when search query changes (immediately for instantSearch or after Enter hit otherwise)
   const updateUrlQueryImpl = (value: string, provider: 'npm' | 'algolia') => {
     const isSameQuery = route.query.q === value && route.query.p === provider
     // Don't navigate away from pages that use ?q for local filtering
@@ -54,23 +77,40 @@ export function useGlobalSearch(place: 'header' | 'content' = 'content') {
       },
     })
   }
+
   const updateUrlQuery = debounce(updateUrlQueryImpl, 250)
 
   function flushUpdateUrlQuery() {
-    updateUrlQuery.flush()
+    // Commit the current query when explicitly submitted (Enter pressed)
+    committedSearchQuery.value = searchQuery.value
+    // When instant search is off the debounce queue is empty, so call directly
+    if (!settings.value.instantSearch) {
+      updateUrlQueryImpl(searchQuery.value, searchProvider.value)
+    } else {
+      updateUrlQuery.flush()
+    }
   }
 
   const searchQueryValue = computed({
     get: () => searchQuery.value,
     set: async (value: string) => {
       searchQuery.value = value
 
+      // When instant search is off, skip debounced URL updates — only flushUpdateUrlQuery commits and navigates
+      if (!settings.value.instantSearch) return
+
       // Leading debounce implementation as it doesn't work properly out of the box (https://github.com/unjs/perfect-debounce/issues/43)
       if (!updateUrlQuery.isPending()) {
         updateUrlQueryImpl(value, searchProvider.value)
       }
       updateUrlQuery(value, searchProvider.value)
     },
   })
-  return { model: searchQueryValue, provider: searchProviderValue, flushUpdateUrlQuery }
+
+  return {
+    model: searchQueryValue,
+    committedModel: committedSearchQuery,
+    provider: searchProviderValue,
+    startSearch: flushUpdateUrlQuery,
+  }
 }

app/composables/useSettings.ts

@@ -29,6 +29,8 @@ export interface AppSettings {
   selectedLocale: LocaleObject['code'] | null
   /** Search provider for package search */
   searchProvider: SearchProvider
+  /** Show search results as you type */
+  instantSearch: boolean
   /** Enable/disable keyboard shortcuts */
   keyboardShortcuts: boolean
   /** Connector preferences */
@@ -54,6 +56,7 @@ const DEFAULT_SETTINGS: AppSettings = {
   selectedLocale: null,
   preferredBackgroundTheme: null,
   searchProvider: import.meta.test ? 'npm' : 'algolia',
+  instantSearch: true,
   keyboardShortcuts: true,
   connector: {
     autoOpenURL: false,

app/pages/index.vue

@@ -1,11 +1,11 @@
 <script setup lang="ts">
 import { SHOWCASED_FRAMEWORKS } from '~/utils/frameworks'
 
-const { model: searchQuery, flushUpdateUrlQuery } = useGlobalSearch()
+const { model: searchQuery, startSearch } = useGlobalSearch()
 const isSearchFocused = shallowRef(false)
 
 async function search() {
-  flushUpdateUrlQuery()
+  startSearch()
 }
 
 const { env } = useAppConfig().buildInfo

app/pages/search.vue

@@ -32,7 +32,11 @@ const updateUrlPage = debounce((page: number) => {
   window.history.replaceState(window.history.state, '', url)
 }, 500)
 
-const { model: searchQuery, provider: searchProvider } = useGlobalSearch()
+const {
+  model: searchQuery,
+  committedModel: committedQuery,
+  provider: searchProvider,
+} = useGlobalSearch()
 const query = computed(() => searchQuery.value)
 
 // Track if page just loaded (for hiding "Searching..." during view transition)
@@ -181,6 +185,7 @@ watch(searchProvider, provider => {
 })
 
 // Use incremental search with client-side caching + org/user suggestions
+// committedQuery only updates on Enter when instant search is off, otherwise tracks query as user types
 const {
   data: results,
   status,
@@ -191,7 +196,7 @@ const {
   suggestions: validatedSuggestions,
   packageAvailability,
 } = useSearch(
-  query,
+  committedQuery,
   searchProvider,
   () => ({
     size: requestedSize.value,
@@ -475,6 +480,9 @@ function handleResultsKeydown(e: KeyboardEvent) {
     const inputValue = (document.activeElement as HTMLInputElement).value.trim()
     if (!inputValue) return
 
+    // When instantSearch is off, commit the query so search starts
+    committedQuery.value = inputValue
+
     // Check if first result matches the input value exactly
     const firstResult = displayResults.value[0]
     if (firstResult?.package.name === inputValue) {
@@ -664,7 +672,7 @@ onBeforeUnmount(() => {
         <SearchProviderToggle />
       </div>
 
-      <section v-if="query" class="results-layout">
+      <section v-if="committedQuery" class="results-layout">
         <LoadingSpinner v-if="showSearching" :text="$t('search.searching')" />
 
         <div

app/pages/settings.vue

@@ -145,7 +145,7 @@ const setLocale: typeof setNuxti18nLocale = locale => {
           </div>
         </section>
 
-        <!-- DATA SOURCE Section -->
+        <!-- SEARCH FEATURES Section -->
         <section>
           <h2 class="text-xs text-fg-muted uppercase tracking-wider mb-4">
             {{ $t('settings.sections.search') }}
@@ -204,6 +204,15 @@ const setLocale: typeof setNuxti18nLocale = locale => {
                 <span class="i-lucide:external-link w-3 h-3" aria-hidden="true" />
               </a>
             </div>
+
+            <div class="border-t border-border my-4" />
+
+            <!-- Instant Search toggle -->
+            <SettingsToggle
+              :label="$t('settings.instant_search')"
+              :description="$t('settings.instant_search_description')"
+              v-model="settings.instantSearch"
+            />
           </div>
         </section>
 

i18n/locales/en.json

@@ -110,7 +110,7 @@
     "sections": {
       "appearance": "Appearance",
       "display": "Display",
-      "search": "Data source",
+      "search": "Search features",
       "language": "Language",
       "keyboard_shortcuts": "Keyboard shortcuts"
     },
@@ -122,6 +122,8 @@
       "algolia": "Algolia",
       "algolia_description": "Uses Algolia for faster search, org and user pages."
     },
+    "instant_search": "Instant search",
+    "instant_search_description": "Show search results as you type, without pressing Enter.",
     "relative_dates": "Relative dates",
     "include_types": "Include {'@'}types in install",
     "include_types_description": "Add {'@'}types package to install commands for untyped packages",

i18n/schema.json

@@ -370,6 +370,12 @@
           },
           "additionalProperties": false
         },
+        "instant_search": {
+          "type": "string"
+        },
+        "instant_search_description": {
+          "type": "string"
+        },
         "relative_dates": {
           "type": "string"
         },