Qif Documentation

Creating Custom Filters with react-Qif

This tutorial will guide you through the process of creating custom filter components using the Qif package.

Step 1: Set up filter state

First, initialize your filters using the useFilters hook with your parsers:

import { useFilters, FiltersProvider } from 'react-qif';
import { parseAsString } from 'nuqs';

const App = () => {
  const filtersInstance = useFilters({
    parsers: {
      search: parseAsString.withDefault(''),
      category: parseAsString.withDefault('test')
    }
  });

  return (
    <FiltersProvider instance={filtersInstance}>
      {/* Your app content */}
    </FiltersProvider>
  );
};

Step 2: Set up NuqsAdapter

Since Qif uses nuqs internally, you need to select and set up the appropriate NuqsAdapter for your framework:

For React Applications

import { NuqsAdapter } from 'nuqs/adapters/react';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <NuqsAdapter>
      <App />
    </NuqsAdapter>
  </StrictMode>
);

For Next.js Applications

import { NuqsAdapter } from 'nuqs/adapters/next';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <NuqsAdapter>{children}</NuqsAdapter>
      </body>
    </html>
  );

For more information about NuqsAdapter configuration, read Docs

Step 3: Create a custom filter component

Now, let's create a custom filter component using the useFiltersContext hook:

import { useFiltersContext } from 'react-qif';

const CustomFilter = ({ name }) => {
  const { setValue, getValue } = useFiltersContext();

  const handleChange = (e) => setValue(name, e.target.value);

  return (
    <div>
      <label htmlFor={name}>{name}</label>
      <input
        id={name}
        type="text"
        value={getValue(name)}
        onChange={handleChange}
        placeholder={`Enter ${name}...`}
      />
    </div>
  );
};

Step 4: Use the custom filter in your app

Now you can use your custom filter component in your app:

import { parseAsString } from 'nuqs';

const App = () => {
  const filtersInstance = useFilters({
    syncWithSearchParams: true,
    parsers: {
      search: parseAsString.withDefault(''),
      category: parseAsString.withDefault('test')
    }
  });

  return (
    <FiltersProvider instance={filtersInstance}>
      <CustomFilter name="search" />
      <CustomFilter name="category" />
      {/* Other components */}
    </FiltersProvider>
  );
};

Step 5: Create a reset button

Let's add a reset button to clear all filters to default values:

import { useFiltersContext } from 'react-qif';

const ResetButton = () => {
  const { reset, isResetDisabled } = useFiltersContext();

  return (
    <button onClick={reset} disabled={isResetDisabled}>
      Reset Filters 
    </button>
  );
};

Step 6: Use filter values

Finally, use the filter values in your components:

import { useFiltersContext } from 'react-qif';

const FilteredContent = () => {
  const { getValue, filters } = useFiltersContext();

  const searchTerm = getValue('search');
  const category = getValue('category');

  // You can also access all filters directly
  console.log('All filters:', filters);

  return (
    <div>
      <h2>Filtered Results</h2>
      <p>Search: {searchTerm}</p>
      <p>Category: {category}</p>
      {/* Render your filtered content here */}
    </div>
  );
};

View on GitHub