React Filter UI

A flexible React component library for building advanced filtering interfaces. This package provides a user-friendly UI for filtering data based on configurable schemas.

Features

• Dynamic field selection based on schema
• Multiple filter logic options (equals, contains, greater than, etc.)
• Special input handling for dates, numbers, booleans, and references
• Edit and remove existing filters
• Theme customization through color hooks
• MongoDB-compatible query generation

Installation

npm install react-filter-ui

or

yarn add react-filter-ui

Basic Usage

import React, { useState, useCallback } from 'react';
import { Filter } from 'react-filter-ui';

const MyDataTable = () => {
  // State for search parameters
  const [searchJson, setSearchJson] = useState({
    page: 1,
    limit: 10,
    search: {}
  });
  
  // State for pagination
  const [pagination, setPagination] = useState({
    page: 1,
    limit: 10,
    total: 0
  });
  
  // Define your data schema for filterable fields
  const filterSchema = [
    {
      serverKey: 'name',
      fieldLabel: 'Name',
      dbType: 'string',
      inputType: 'text',
      status: true,
      enabled: true,
      required: false
    },
    {
      serverKey: 'age',
      fieldLabel: 'Age',
      dbType: 'number',
      inputType: 'number',
      status: true,
      enabled: true,
      required: false
    },
    {
      serverKey: 'isActive',
      fieldLabel: 'Active',
      dbType: 'boolean',
      inputType: 'switch',
      status: true,
      enabled: true,
      required: false
    },
    {
      serverKey: 'createdAt',
      fieldLabel: 'Created Date',
      dbType: 'date',
      inputType: 'date',
      status: true,
      enabled: true,
      required: false
    }
  ];
  
  // Function to load data based on filters
  const loadData = useCallback((paginationParams, searchParams) => {
    // Make API call to your backend with the search parameters
    console.log('Loading data with:', paginationParams, searchParams);
    
    // Example API call:
    // api.fetchData(searchParams).then(response => {
    //   setData(response.data);
    //   setPagination({
    //     page: response.page,
    //     limit: response.limit,
    //     total: response.total
    //   });
    // });
  }, []);
  
  // Handle filter changes
  const handleFilterChange = useCallback((updatedSearchJson) => {
    // Prepare the formatted search JSON
    const formattedSearchJson = {
      page: 1, // Always reset to page 1 when filters change
      limit: pagination.limit || 10,
      search: (updatedSearchJson?.search || {})
    };
    
    // Move nested payload.search to top-level if needed
    if (updatedSearchJson?.payload?.search) {
      formattedSearchJson.search = updatedSearchJson.payload.search;
    }
    
    // Update the state
    setSearchJson(formattedSearchJson);
    
    // Schedule the API call (the loadData function will handle deduplication)
    loadData(formattedSearchJson, formattedSearchJson);
  }, [loadData, pagination.limit]);
  
  return (
    <div>
      <h1>My Data Table</h1>
      
      {/* Filter component */}
      {filterSchema.length > 0 && (
        <Filter
          schema={filterSchema}
          searchJson={searchJson}
          loadData={loadData}
          paginationData={pagination}
          collectionName="Users"
          onFilterChange={handleFilterChange}
        />
      )}
      
      {/* Your data table component goes here */}
      <div className="table-container">
        {/* Table implementation */}
      </div>
    </div>
  );
};

export default MyDataTable;

API Reference

Filter Component

| Prop | Type | Description | |------|------|-------------| | schema | Array | Array of field objects defining which fields can be filtered | | searchJson | Object | Current search parameters object | | loadData | Function | Function to call when filters change to reload data | | paginationData | Object | Pagination parameters like page, limit, total | | collectionName | String | Name of the collection/table being filtered (displayed in UI) | | onFilterChange | Function | Callback when filters change |

Schema Format

Each field in the schema array should have the following properties:

{
  serverKey: 'fieldName',        // Field key in the database
  fieldLabel: 'Field Label',     // Human-readable label
  dbType: 'string',              // Data type: 'string', 'number', 'date', 'boolean', 'ref' 
  inputType: 'text',             // UI input type
  status: true,                  // Whether field is available
  enabled: true,                 // Whether field is enabled
  required: false                // Whether field is required
}

Generated Query Format

The component generates MongoDB-compatible queries in the format:

{
  page: 1,
  limit: 10,
  search: {
    $and: [
      { fieldName: { $eq: "value" } },
      { age: { $gte: 21 } }
      // More conditions...
    ]
  }
}

Customizing Colors

The component uses the useColors hook to support theming. You can customize the colors by storing primaryColor and secondaryColor in localStorage:

// Example to set custom colors
const userData = {
  userData: {
    primaryColor: { hex: '#4a90e2' },
    secondaryColor: { hex: '#ffffff' }
  }
};

localStorage.setItem('imzUser', JSON.stringify(userData));

Advanced Features

Using FilterUI directly

For more control, you can use the FilterUI component directly:

import { FilterUI } from 'react-filter-ui';

// ...

<FilterUI
  schema={transformedSchema}
  activeFilters={activeFilters}
  setActiveFilters={setActiveFilters}
  onFilterChange={handleFilterChange}
  searchJson={searchJson}
  loadData={loadData}
  paginationData={pagination}
/>

Using the utility functions

import { 
  buildMongoQuery, 
  buildCompoundQuery,
  getLogicOptions,
  needsSpecialValueHandling 
} from 'react-filter-ui';

// Build a MongoDB query for a field
const query = buildMongoQuery('age', '$gte', 18, schema.schema.fields);

// Combine multiple queries
const queries = [
  { name: { $eq: 'John' } },
  { age: { $gte: 18 } }
];
const compoundQuery = buildCompoundQuery(queries);

License

MIT