Package Documentation: @ventcode/filters-web

Overview

The @ventcode/filters-web package provides a system for managing and synchronizing filters in web React-based applications. It builds upon the functionality of @ventcode/filters-core, adding additional support and utilities for working with URL search parameters and React contexts, using @tanstack/react-router.

This package is useful for scenarios where filtering values need to stay in sync with URL parameters.

Installation

npm install @ventcode/filters-web

Peer Dependencies

Make sure the following dependencies are also installed in your project:

• React: ^19.2.0
• React DOM: ^19.2.0
• TypeScript: ^5.5.3
• @tanstack/react-router: ^1.46.2
• @ventcode/filters-core: workspace:*

Features

• Filters Context Provider: A React context for managing filter values, submission, and reset.
• URL Parameter Synchronization: A specialized component (SearchParamsFilters) for handling filter states that automatically syncs with URL search parameters using @tanstack/react-router.

Exports & Components

FiltersProvider

Description

A context provider component, exported from @ventcode/filters-core, that allows managing filter values in the application. It supports default values, initial values, and provides callback mechanisms for updates.

Parameters

• initialValues: Initial values for the filters (optional).
• defaultValues: onReset function resets the filter context to this prop value (optional).
• children: React child components.
• onSubmit: Callback function executed when filters are submitted, accepts current filters context values.
• onReset: Callback function executed before filters reset, accepts defaultValues.

Example

import { FiltersProvider } from '@ventcode/filters-web';

const App = () => {
  const handleSubmit = (values) => console.log('Submitted Filters:', values);

  return (
    <FiltersProvider
      initialValues={{ status: 'active' }}
      defaultValues={{ status: 'all' }}
      onSubmit={handleSubmit}
    >
      <YourComponent />
    </FiltersProvider>
  );
};

SearchParamsFilters

Description

The SearchParamsFilters component synchronizes URL search parameters with context filter values, using @tanstack/react-router. It performs two key functions:

1. Reading from URL:

   • Takes URL search parameters and filters them to only include keys matching defaultValues
   • Passes the filtered parameters to a FiltersProvider context for further use

2. Writing to URL:

   • Provides an onSubmit function that pushes active filters from the context back to the URL
   • Removes empty or unset filter values from the URL while preserving other query parameters

Parameters

• children: React child components.
• defaultValues: Default filter values. Only provided keys will be stored in the context.

Example

import { SearchParamsFilters } from '@ventcode/filters-web';

const SearchFilters = () => (
  <SearchParamsFilters defaultValues={{ category: 'all', sort: 'asc' }}>
    <YourComponent />
  </SearchParamsFilters>
);

Example Usage

Synchronizing Filters with URL Search Parameters

This example demonstrates how to use SearchParamsFilters to manage filters synchronized with URL query parameters.

Example: Update filter value:

import React from 'react';
import { SearchParamsFilters, useFilter } from '@ventcode/filters-web';

const MyPage = () => (
    // Initialize filters context with the following values and "listen" for changes 
    <SearchParamsFilters defaultValues={{ status: 'all', numbers: ['1'] }}>
      <YourFiltersComponent />
    </SearchParamsFilters>
  );

const YourFiltersComponent = () => {
  // Change filter value in FiltersProvider
  const { value: status, setValue: setStatus } = useFilter<string>('status')
  const { value: numbers, setValue: setNumbers } = useFilter<string[]>('numbers')

  // onSubmit pushes values from FiltersProvider context to URL
  const { onSubmit } = useFiltersContext()

  // Checkbox checking logic
  const onNumbersChange = (e: ChangeEvent<HTMLInputElement>) => {
    const newValue = e.currentTarget.checked
      ? [...(numbers ?? []), e.currentTarget.value]
      : (numbers?.filter((number) => number !== e.currentTarget.value) ?? [])

    setNumbers(newValue)
  }

  const isNumberSelected = (number: string) => numbers?.includes(number)

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault()

        // Push new filters to URL on form submit
        onSubmit()
      }}
    >
      <select value={status} onChange={(e) => setStatus(e.currentTarget.value)}>
        <option value='all'>All</option>
        <option value='active'>Active</option>
        <option value='inactive'>Inactive</option>
      </select>

      <fieldset>
        <legend>Choose your number:</legend>

        <label>
          1
          <input type='checkbox' value='1' checked={isNumberSelected('1')} onChange={onNumbersChange} />
        </label>

        <label>
          2
          <input type='checkbox' value='2' checked={isNumberSelected('2')} onChange={onNumbersChange} />
        </label>

        <label>
          3
          <input type='checkbox' value='3' checked={isNumberSelected('3')} onChange={onNumbersChange} />
        </label>
      </fieldset>

      <button type='submit'>Submit</button>
    </form>
  )
}

Example: test_param will NOT be tracked:

// # Current URL: "/test_param=123"

import React from 'react';
import { SearchParamsFilters } from '@ventcode/filters-web';

const MyPage = () => {
  return (
    <SearchParamsFilters defaultValues={{ status: 'all' }}>
      <YourFiltersComponent />
    </SearchParamsFilters>
  );
};

const YourFiltersComponent = () => {
  const filters = useFiltersContext() // filters: { status: 'all' }
  
  return <div>...</div>
}

Example: test_param will be tracked:

// # Current URL: "/test_param=123"

import React from 'react';
import { SearchParamsFilters } from '@ventcode/filters-web';

const MyPage = () => {
  return (
    <SearchParamsFilters defaultValues={{ status: 'all', test_param: null }}>
      <YourFiltersComponent />
    </SearchParamsFilters>
  );
};

const YourFiltersComponent = () => {
  // Most recent value from params will be returned here:
  const filters = useFiltersContext() // filters: { status: 'all', test_param: 123 }
  
  return <div>...</div>
}

With this setup, any changes to the filters reflect in the URL, and refreshing or sharing the URL preserves the filter state.