🎯 Qif
Powerful filtering system for React.js applications
[](https://www.npmjs.com/package/react-qif)
[](https://bundlephobia.com/result?p=react-qif@latest)
[](https://GitHub.com/hsnards/qif/contributors/)
[](https://github.com/hsnards/qif/blob/master/LICENSE)
[](https://github.com/hsnards/qif/compare)
## ✨ Features
- 🔄 **Centralized State System** - Efficient application state management
- 🎨 **Headless UI** - Flexible, unstyled components for full customization
- 🧩 **Composable Components** - Build complex UIs with simple, reusable parts
- 🔗 **URL Sync** - Built on nuqs for robust URL state management
- 🛠️ **Developer-Friendly API** - Intuitive design for seamless development
- ⚡ **Performance Optimized** - Smooth handling of large datasets
## 📦 Installation
```bash
# Using npm
npm install react-qif nuqs
# Using yarn
yarn add react-qif nuqs
```
## 🚀 Quick Start
```tsx
import { useFilters, FiltersProvider, useFiltersContext } from 'react-qif';
import { parseAsString } from 'nuqs';
type FiltersType = {
search: string;
category: string;
};
const App = () => {
const filtersInstance = useFilters({
parsers: {
search: parseAsString.withDefault(''),
category: parseAsString.withDefault('test')
}
});
return (
);
};
const SearchFilter = () => {
const { getValue, setValue } = useFiltersContext();
return (
setValue('search', e.target.value)}
/>
);
};
```
## 🔧 Setup
### 1. Configure NuqsAdapter
#### For Next.js:
```tsx
import { NuqsAdapter } from 'nuqs/adapters/next';
export default function RootLayout({ children }) {
return (
{children}
);
}
```
#### For React:
```tsx
import { NuqsAdapter } from 'nuqs/adapters/react';
createRoot(document.getElementById('root')!).render(
);
```
## 📚 API Reference
### FiltersProvider Props
- `instance`: Filter instance created by useFilters
- `children`: React nodes
### useFilters Hook Options
```tsx
interface UseFiltersOptions {
syncWithSearchParams?: boolean;
parsers: UseQueryStatesKeysMap;
}
```
### useFiltersContext Hook
Returns an object with the following methods:
- `register(name, defaultValue)`: Register a filter with default value
- `unregister(name)`: Remove a filter
- `setValue(name, value)`: Update filter value
- `getValue(name)`: Get current filter value
- `reset()`: Reset all filters to defaults
- `isResetDisabled`: Check if reset is available
## 🔄 Client-Side Filtering
Unlike nuqs, Qif also supports client-side filtering. By setting `syncWithSearchParams` to `false`, no parameters will be added to the URL. This is useful for temporary filters or when you don't want to persist the filter state in the URL.
### Client-Side Example
```tsx
const App = () => {
const filtersInstance = useFilters({
syncWithSearchParams: false, // Disable URL synchronization
parsers: {
search: parseAsString.withDefault(''),
category: parseAsString.withDefault('all')
}
});
return (
);
};
const ProductFilters = () => {
const { getValue, setValue } = useFiltersContext();
return (
setValue('search', e.target.value)}
placeholder="Search products..."
/>
);
};
const ProductList = () => {
const { getValue } = useFiltersContext();
const searchTerm = getValue('search') as string;
const category = getValue('category') as string;
// Filter your products based on searchTerm and category
const filteredProducts = products.filter(product => {
const matchesSearch = product.name.toLowerCase().includes(searchTerm.toLowerCase());
const matchesCategory = category === 'all' || product.category === category;
return matchesSearch && matchesCategory;
});
return (
{filteredProducts.map(product => (
))}