SSE Hooks

useSearchWithSuggestions

A comprehensive hook for building "Command Palette" or "Omnibar" style search interfaces. * It provides "Ghost Text" autocomplete (like Google search), command scoping (like Slack's / commands), and keyboard support. It handles the complex logic of parsing input strings to separate commands from queries.

Installation

npx sse-hooks add use-search-with-suggestions

yarn dlx sse-hooks add use-search-with-suggestions

pnpm dlx sse-hooks add use-search-with-suggestions

deno run -A npm:sse-hooks add use-search-with-suggestions

bunx sse-hooks add use-search-with-suggestions

Usage

example.ts

import { useSearchWithSuggestions } from "./{hooks file}";

const users = [
  { id: 1, name: "Alice", role: "admin" },
  { id: 2, name: "Bob", role: "user" },
];
const { inputProps, ghostText, filteredData, isSuggestionAvailable } =
  useSearchWithSuggestions(
    users,
    ["name"], // Default search key
    {
      commands: [
        // Typing ":role admin" will filter by role
        { trigger: "role", scope: "role" },
        // Typing ":admins" will run a custom filter function
        { trigger: "admins", filter: (u) => u.role === "admin" },
      ],
    },
  );
return (
  <div className="search-container">
    <div className="input-wrapper relative">
      // Ghost Layout
      <input
        className="absolute text-gray-300 bg-transparent pointer-events-none"
        value={ghostText}
        readOnly
      />
      // The Actual Input
      <input className="relative bg-transparent" {...inputProps} />
    </div>
    <ul>
      {filteredData.map((u) => (
        <li key={u.id}>{u.name}</li>
      ))}
    </ul>
  </div>
);

API

Parameters

Prop	Default	Type
`data`	-	`T[]` The array of data objects to search through.
`searchKeys`	-	`any` An array of keys (e.g., `['name', 'email']`) to search against by default.
`config`	-	`BaseSearchConfig<T>` Optional configuration object.

Returns

Return Value	Default	Type
`return`	-	`UseSearchSuggestionsResult<T>` Hook return value

Types Aliases

No specific type aliases defined for this component.

Changelog

2b25b — feat: add useSearchWithSuggestions hook for enhanced search functionality

useCallbackRef

A custom hook that converts a callback to a ref to avoid triggering re-renders when passed as a prop or avoid re-executing effects when passed as a dependency

useSSR

Custom hook that detects the current environment (Browser, Server, or Native) and capability support (Workers, EventListeners). useful for avoiding hydration mismatches.