A lightweight and reusable React hook for filtering lists with accent normalization, punctuation removal and TypeScript support.
npm install @perch33/react-usefilter-hookA lightweight and reusable React hook for filtering lists with accent normalization, punctuation removal, and TypeScript support.
Ideal for search bars, dynamic lists, admin dashboards, e-commerce filters, etc.
!npm
!downloads
!license
!types
!Next.js
---
- 🔠 Removes accents (á → a)
- ✂️ Removes punctuation and special characters
- 🔎 Case-insensitive search
- ⚛️ Fully typed with TypeScript
- 🚀 Next.js App Router Compatible ("use client" included)
- 🔁 Auto-updates when data changes
- 🔧 Accepts custom error component
- 🧩 Framework-agnostic, works in any React project
---
``sh`
npm install @perch33/react-usefilter-hook
or
`sh`
yarn add @perch33/react-usefilter-hook
`tsx
import { useFilter } from "@perch33/react-usefilter-hook";
const products = [
{ title: "Cámara Fotográfica" },
{ title: "Microfono" },
{ title: "Cable HDMI" },
];
export default function App() {
const { filterText, filteredData, error, handleFilterChange } = useFilter(
products,
"title",
No results found
, return (
🎯 Advanced Example
tsx
const { filterText, filteredData, error, handleFilterChange } = useFilter(
users,
"name",
No users found,
);return (
<>
placeholder="Search users"
value={filterText}
onChange={handleFilterChange}
/>
{filteredData.map((p, i) => (
- {p.title}
))}
{error}
);
`🧠 API Reference
tsx
useFilter(data, key, errorComponent);
`| Param | Type | Description |
| ---------------- | ----------------- | --------------------------------- |
|
| T[] | Array of objects to filter |
| key | keyof T | Object field used for filtering |
| errorComponent | React.ReactNode | Element displayed when no matches |Returns
| Property | Type | Description |
| -------------------- | ------------------------------------ | ------------------------------------- |
|
filterText | string | Current normalized search text |
| filteredData | T[] | List filtered according to user input |
| error | React.ReactNode \| null | Error component if no matches |
| handleFilterChange | (e: ChangeEvent | Input handler |$3
- This hook automatically:
- Converts text to lowercase
- Removes accents (áéíóú → aeiou)
- Removes punctuation and special characters
- Performs a normalized comparison
- Filters in real time as the user types
---
🔍 Used in Production (Real Examples)
This hook is currently used in my personal website:
- 🎼 Music Scores / Partituras
Live search using
useFilter to filter music scores dynamically.
👉 https://www.percychuzon.com/partituras- ✍️ Blog
Used to filter blog posts instantly with accent-insensitive matching.
👉 https://www.percychuzon.com/blog
These sections demonstrate real-world usage of the hook with dynamic content,
search inputs, and accent-normalized filtering.
$3
- Product search inputs
- Admin panel filters
- Searchable dropdowns
- User lists
- Blog post search
- Table filtering
- Autocomplete components
📁 Project Structure
Your installation will contain:
`
dist/
├─ cjs/
├─ esm/
├─ types/
src/
README.md
Percy Chuzon
📧 contacto@percychuzon.com
🌐 https://www.percychuzon.com