Introduction

In today's digital age, search functionality is more than just a nice-to-have feature—it's a necessity. Whether users are browsing an online store, managing a list of contacts, or exploring content on a blog, quickly finding relevant information is crucial to delivering a seamless user experience. As developers, implementing an efficient and intuitive search system can often be challenging, especially when working with complex data structures or large datasets.

This is where custom React hooks come into play. Hooks offer a powerful way to encapsulate and reuse logic across components, making your codebase cleaner and more maintainable. In this article, I’ll introduce you to a custom React hook I’ve developed called useSearch. This hook simplifies the process of adding search functionality to your React applications by providing a reusable solution that can handle a wide variety of data types and structures.

We’ll explore the motivation behind creating the useSearch hook, break down its core functionality, and walk through how you can integrate it into your projects. By the end of this article, you'll have a powerful tool at your disposal to implement search features with ease and efficiency.

The Motivation Behind useSearch

In any modern web application, the ability to search through data is essential. Whether it’s filtering products in an e-commerce store, searching for users in an admin dashboard, or narrowing down posts in a blog, a robust search feature can significantly enhance user experience.

However, implementing a search functionality that is both flexible and efficient can be challenging. Developers often write repetitive code to handle different data structures and search requirements. This is where the idea of a custom hook, like useSearch, comes into play.

The primary motivation behind creating the useSearch hook was to build a reusable, generic solution that could be easily integrated into any React project. Instead of rewriting search logic for every new component, useSearch developers can abstract this functionality, making the codebase cleaner and more maintainable.

---

Breaking Down the useSearch Hook

The Complete Code

Here’s the complete code for the useSearch hook:

"use client";
import React, { useState, useMemo } from "react";

// Utility type to extract keys of T that have string values
type StringKeys<T> = {
  [K in keyof T]: T[K] extends string ? K : never;
}[keyof T];

// Interface for the hook's props
interface UseSearchProps<T> {
  data: T[];
  accessorKey: StringKeys<T>[];
}

// Custom hook
const useSearch = <T>({ data, accessorKey }: UseSearchProps<T>) => {
  const [searchTerm, setSearchTerm] = useState<string>("");

  // Memoize the searchedData calculation for performance optimization
  const searchedData = useMemo(() => {
    console.log(searchTerm);
    return data.filter((item) =>
      accessorKey.some((key) => {
        if (!searchTerm) return true; // If searchTerm is empty, include all items

        const value = item[key];
        if (!value) return false; // If the value is undefined or null, exclude the item

        if (typeof value === "string") {
          return value.toLowerCase().includes(searchTerm.toLowerCase());
        } else if (Array.isArray(value)) {
          return value.some((innerValue) =>
            typeof innerValue === "string"
              ? innerValue.toLowerCase().includes(searchTerm.toLowerCase())
              : false
          );
        }
        return false;
      })
    );
  }, [data, accessorKey, searchTerm]);

  return { searchedData, searchTerm, setSearchTerm };
};

export default useSearch;

Understanding the Components

1. Utility Type: StringKeys<T>

   The first component of the useSearch hook is the StringKeys<T> utility type. This TypeScript construct is designed to extract the keys from a generic type T that correspond to string values. By doing this, we ensure that the hook only attempts to search within properties that are strings, which makes sense for search functionality.

    type StringKeys<T> = {
      [K in keyof T]: T[K] extends string ? K : never;
    }[keyof T];
   

   This utility type allows the hook to be generic, which means it can be used with any data structure as long as the keys being searched hold string values. This adds a layer of type safety, ensures that the hook is only applied to valid fields, and reduces potential runtime errors.

2. Hook Interface: UseSearchProps<T>

   Next, we define the UseSearchProps<T> interface, which describes the expected props for the useSearch hook. This interface includes two properties:

   • data: An array of items of type T, representing the dataset to be searched.

   • accessorKey: An array of keys (determined by StringKeys<T>) that indicate which fields of the data should be included in the search.

    interface UseSearchProps<T> {
      data: T[];
      accessorKey: StringKeys<T>[];
    }

By defining this interface, we make the hook adaptable to any data structure, as long as the fields specified in accessorKey are strings. This is particularly useful in complex applications where data can vary significantly across different components.

3. State Management with useState

   The useSearch hook utilizes React's useState to store the search term that users input.

    const [searchTerm, setSearchTerm] = useState<string>("");
   

4. Memoization with useMemo

   The searchedData is calculated using the useMemo hook, which memoizes the result of the search operation to optimize performance. It prevents unnecessary recalculations of the filtered data when the search term or data hasn’t changed.

    const searchedData = useMemo(() => {
      // Filtering logic here...
    }, [data, accessorKey, searchTerm]);
   

   Memoization is useful in scenarios where the dataset is large or when the search operation is computationally expensive. By only recalculating when necessary, we can significantly improve the performance of our application.

5. Filtering Logic:

   This part of the code checks each item in the data array against the search term, considering only the fields specified in accessorKey.

    return data.filter((item) =>
      accessorKey.some((key) => {
        if (!searchTerm) return true; // If searchTerm is empty, include all items
   
        const value = item[key];
        if (!value) return false; // If the value is undefined or null, exclude the item
   
        if (typeof value === "string") {
          return value.toLowerCase().includes(searchTerm.toLowerCase());
        } else if (Array.isArray(value)) {
          return value.some((innerValue) =>
            typeof innerValue === "string"
              ? innerValue.toLowerCase().includes(searchTerm.toLowerCase())
              : false
          );
        }
        return false;
      })
    );
   

   This logic handles several scenarios:

   • Empty Search Term: If the search term is empty, all items are included.

   • String Matching: It checks if the string value includes the search term, ignoring the case.

   • Array Handling: If the value is an array, it checks if any string within the array matches the search term.

Filtering Logic

1. Data Filtering: The data.filter() method iterates over each item in the dataset, applying a filtering condition to determine whether the item should be included in the searchedData.

2. Accessor Key Check: For each item, the accessorKey.some() method checks if any of the specified keys contain the search term. This allows the search to be performed across multiple fields of the data objects.

3. Search Term Handling:

   • Empty Search Term: If the searchTerm is empty (!searchTerm), the condition returns true, including all items in the results. This ensures that the full dataset is displayed when no search query is entered.

4. Value Retrieval and Type Checking:

   • Undefined or Null Values: If the value corresponding to the accessor key is undefined or null (!value), the condition returns false, excluding the item from the results.

   • String Values: If the value is a string, the hook checks if it includes the searchTerm, ignoring case by converting both to lowercase.

       return value.toLowerCase().includes(searchTerm.toLowerCase());
     

   • Array Values: If the value is an array, the hook iterates through each element, checking if any string within the array includes the searchTerm.

       return value.some((innerValue) =>
         typeof innerValue === "string"
           ? innerValue.toLowerCase().includes(searchTerm.toLowerCase())
           : false
       );
     

5. Edge Cases:

   • Non-string and Non-array Values: If the value is neither a string nor an array, the condition returns false, excluding the item from the results.

Integrating useSearch into Your React Project

To fully understand how the useSearch hook works, we have to first see it in action.

1. Setting Up the Hook

First, ensure that the useSearch hook is correctly imported into your component. Assuming you’ve placed the hook in a file named useSearch.ts, the import statement would look like this:

    import useSearch from './useSearch';

2. Preparing Your Data

For this example, let’s say we have a list of users, each with a name, email, and roles:

    const users = [
      { name: "John Doe", email: "john@example.com", roles: ["admin", "user"] },
      { name: "Jane Smith", email: "jane@example.com", roles: ["user"] },
      { name: "Emily Davis", email: "emily@example.com", roles: ["admin"] },
      // more users...
    ];

3. Using the useSearch Hook

With your data in place, it's time to use the useSearch hook. You'll need to specify the dataset (users in this case) and the keys you want the hook to search within. In our example, we’ll search within name, email, and roles:

    const { searchedData, searchTerm, setSearchTerm } = useSearch({
      data: users,
      accessorKey: ["name", "email", "roles"],
    });

Here’s a breakdown of what’s happening:

• searchedData: This contains the filtered list of users based on the current search term.

• searchTerm: This is the current search term entered by the user.

• setSearchTerm: This function updates the searchTerm state as the user types.

4. Creating the Search Input

Next, create an input field that will capture the user’s search query. This input field will update the searchTerm state, which in turn triggers the useSearch hook to filter the data:

    <input
      type="text"
      value={searchTerm}
      onChange={(e) => setSearchTerm(e.target.value)}
      placeholder="Search users..."
    />

5. Displaying the Search Results

Finally, render the filtered list of users (searchedData) in your component. Here’s a simple way to display the search results:

    <ul>
      {searchedData.map((user, index) => (
        <li key={index}>
          <strong>{user.name}</strong> - {user.email}
        </li>
      ))}
    </ul>

This will display a list of users that match the current search term based on their name, email, or roles.

Putting It All Together

Here's what the complete component might look like:

    import React, { useState } from 'react';
    import useSearch from './useSearch';

    const UserSearch = () => {
      const users = [
        { name: "John Doe", email: "john@example.com", roles: ["admin", "user"] },
        { name: "Jane Smith", email: "jane@example.com", roles: ["user"] },
        { name: "Emily Davis", email: "emily@example.com", roles: ["admin"] },
        // more users...
      ];

      const { searchedData, searchTerm, setSearchTerm } = useSearch({
        data: users,
        accessorKey: ["name", "email", "roles"],
      });

      return (
        <div>
          <input
            type="text"
            value={searchTerm}
            onChange={(e) => setSearchTerm(e.target.value)}
            placeholder="Search users..."
          />
          <ul>
            {searchedData.map((user, index) => (
              <li key={index}>
                <strong>{user.name}</strong> - {user.email}
              </li>
            ))}
          </ul>
        </div>
      );
    };

    export default UserSearch;

Bonus: Adding Real-Time Search with Debouncing

To optimize the useSearch hook with search functionality, we can incorporate a debouncing feature. Debouncing ensures that the search function doesn't trigger excessively, which is particularly useful when dealing with large datasets or when making API calls.

Here’s the updated code for the useSearch hook, now with an optional debounce feature:

import React, { useState, useMemo, useEffect, useRef } from "react";

// Utility type to extract keys of T that have string values
type StringKeys<T> = {
  [K in keyof T]: T[K] extends string ? K : never;
}[keyof T];

// Interface for the hook's props
interface UseSearchProps<T> {
  data: T[];
  accessorKey: StringKeys<T>[];
  debounce?: {
    enabled: boolean;
    debounceTime?: number;
  };
}

// Custom hook with optional debouncing
const useSearch = <T>({
  data,
  accessorKey,
  debounce = { enabled: false, debounceTime: 300 },
}: UseSearchProps<T>) => {
  const [searchTerm, setSearchTerm] = useState<string>("");
  const [debouncedSearchTerm, setDebouncedSearchTerm] = useState<string>(searchTerm);

  const debounceTimeout = useRef<NodeJS.Timeout | null>(null);

  useEffect(() => {
    if (debounce.enabled) {
      if (debounceTimeout.current) {
        clearTimeout(debounceTimeout.current);
      }

      debounceTimeout.current = setTimeout(() => {
        setDebouncedSearchTerm(searchTerm);
      }, debounce.debounceTime);

      return () => {
        if (debounceTimeout.current) {
          clearTimeout(debounceTimeout.current);
        }
      };
    } else {
      setDebouncedSearchTerm(searchTerm);
    }
  }, [searchTerm, debounce.enabled, debounce.debounceTime]);

  const searchedData = useMemo(() => {
    console.log(debouncedSearchTerm);
    return data.filter((item) =>
      accessorKey.some((key) => {
        if (!debouncedSearchTerm) return true; // If searchTerm is empty, include all items

        const value = item[key];
        if (!value) return false; // If the value is undefined or null, exclude the item

        if (typeof value === "string") {
          return value.toLowerCase().includes(debouncedSearchTerm.toLowerCase());
        } else if (Array.isArray(value)) {
          return value.some((innerValue) =>
            typeof innerValue === "string"
              ? innerValue.toLowerCase().includes(debouncedSearchTerm.toLowerCase())
              : false
          );
        }
        return false;
      })
    );
  }, [data, accessorKey, debouncedSearchTerm]);

  return { searchedData, searchTerm, setSearchTerm };
};

export default useSearch;

What’s Happening?

• Debouncing Logic: The debounce object is an optional parameter that allows you to control whether debouncing is enabled (enabled: boolean) and, if so, how long to wait before processing the input (debounceTime: number).

• useEffect: The hook waits for the user to stop typing for a specified amount of time (debounceTime) before updating the search results. This prevents unnecessary filtering operations while the user is still typing, leading to better performance.

Conclusion

The useSearch hook provides a flexible and powerful way to implement search functionality in your React applications. By allowing you to specify which fields to search across and incorporating performance optimizations like useMemo, it ensures that your application remains responsive even with large datasets.

The bonus feature of adding debouncing further enhances this hook by preventing unnecessary renders and search operations while the user is typing. This makes it particularly useful for real-time search scenarios, where performance is critical.

With this hook, you can easily integrate efficient and user-friendly search capabilities into your projects, providing a better experience for your users. Whether you're building a simple list filter or a more complex search interface, the useSearch hook offers a solid foundation to work from.