SSE Hooks

useSearchWithSuggestions

A comprehensive hook for building "Command Palette" or "Omnibar" style search interfaces.

Installation

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

npm install sse-hooks

Usage

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>
);

import { useSearchWithSuggestions } from "sse-hooks";

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

Name	Type	Description
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`	Optional configuration object.

Return Value

Returns UseSearchSuggestionsResult.

Object containing query state, filtered results, and UI props.

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).