feat: add onEmpty callback to Command

README.md

@@ -128,6 +128,16 @@ A third argument, `keywords`, can also be provided to the filter function. Keywo
 />
 ```
 
+You can listen for when a search query produces no results with `onEmpty`. Useful for analytics, triggering an AI fallback, or capturing unmet user intent:
+
+```tsx
+<Command
+  onEmpty={(search) => {
+    console.log('No results for', search)
+  }}
+/>
+```
+
 Or disable filtering and sorting entirely:
 
 ```tsx

cmdk/src/index.tsx

@@ -118,6 +118,10 @@ type CommandProps = Children &
      * Set to `false` to disable ctrl+n/j/p/k shortcuts. Defaults to `true`.
      */
     vimBindings?: boolean
+    /**
+     * Event handler called when the search query produces no results.
+     */
+    onEmpty?: (search: string) => void
   }
 
 type Context = {
@@ -198,6 +202,7 @@ const Command = React.forwardRef<HTMLDivElement, CommandProps>((props, forwarded
     loop,
     disablePointerSelection = false,
     vimBindings = true,
+    onEmpty,
     ...etc
   } = props
 
@@ -240,6 +245,12 @@ const Command = React.forwardRef<HTMLDivElement, CommandProps>((props, forwarded
           filterItems()
           sort()
           schedule(1, selectFirstItem)
+
+          // Notify when filtering produces no results
+          const search = value as string
+          if (state.current.filtered.count === 0 && search.trim()) {
+            propsRef.current.onEmpty?.(search)
+          }
         } else if (key === 'value') {
           // Force focus input or root so accessibility works
           if (document.activeElement.hasAttribute('cmdk-input') || document.activeElement.hasAttribute('cmdk-root')) {

test/pages/props.tsx

@@ -7,6 +7,7 @@ const Page = () => {
   const [search, setSearch] = React.useState('')
   const [shouldFilter, setShouldFilter] = React.useState(true)
   const [customFilter, setCustomFilter] = React.useState(false)
+  const [emptySearch, setEmptySearch] = React.useState('')
   const router = useRouter()
 
   React.useEffect(() => {
@@ -21,6 +22,7 @@ const Page = () => {
     <div>
       <div data-testid="value">{value}</div>
       <div data-testid="search">{search}</div>
+      <div data-testid="emptySearch">{emptySearch}</div>
 
       <button data-testid="controlledValue" onClick={() => setValue('anteater')}>
         Change value
@@ -33,6 +35,7 @@ const Page = () => {
         shouldFilter={shouldFilter}
         value={value}
         onValueChange={setValue}
+        onEmpty={setEmptySearch}
         filter={
           customFilter
             ? (item: string | undefined, search: string | undefined) => {

test/props.test.ts

@@ -41,4 +41,17 @@ test.describe('props', async () => {
     await page.goto('/props?initialValue=anteater')
     await expect(page.locator(`[cmdk-item][aria-selected="true"]`)).toHaveAttribute('data-value', 'anteater')
   })
+
+  test('onEmpty is called when search produces no results', async ({ page }) => {
+    await page.goto('/props')
+    await expect(page.locator(`[data-testid=emptySearch]`)).toHaveText('')
+    await page.locator(`[cmdk-input]`).fill('zzz')
+    await expect(page.locator(`[data-testid=emptySearch]`)).toHaveText('zzz')
+  })
+
+  test('onEmpty is not called when results exist', async ({ page }) => {
+    await page.goto('/props')
+    await page.locator(`[cmdk-input]`).fill('ant')
+    await expect(page.locator(`[data-testid=emptySearch]`)).toHaveText('')
+  })
 })