AkiFilter

Akifilter is a schema-driven filter component that provides a powerful, declarative way to build filter interfaces.

It handles form state, persistence, visibility management, and applied filter chips automatically.

Installation

pnpm add @akinon/akifilter

Basic Usage

import { Akifilter, filterField, type AkifilterSchema } from '@akinon/akifilter';

interface FilterValues {
  name: string;
  status: string;
  createdAt: Date | null;
}

const filterSchema: AkifilterSchema<FilterValues> = [
  filterField<FilterValues>()
    .key('name')
    .type('text')
    .label('Name')
    .placeholder('Search by name...')
    .visible()
    .build(),
  filterField<FilterValues>()
    .key('status')
    .type('select')
    .label('Status')
    .placeholder('Select status')
    .options([
      { label: 'Active', value: 'active' },
      { label: 'Inactive', value: 'inactive' },
      { label: 'Pending', value: 'pending' }
    ])
    .visible()
    .build(),
  filterField<FilterValues>()
    .key('createdAt')
    .type('date')
    .label('Created Date')
    .placeholder('Select date')
    .build()
];

export const ProductFilters = () => {
  const handleValuesChange = (values: Partial<FilterValues>) => {
    console.log('Filter values changed:', values);
    // Fetch data with new filter values
  };

  return (
    <Akifilter
      filterSchema={filterSchema}
      onValuesChange={handleValuesChange}
      storageNamespace="products"
    />
  );
};

Props

Prop	Type	Description
filterSchema	AkifilterSchema<T>	Declarative description of the filter fields
storageNamespace	string	Optional namespace for local storage persistence
defaultValues	Partial<T>	Default values supplied by the host application
onValuesChange	(values: Partial<T>) => void	Callback on every value change with normalised payload
onVisibleFieldsChange	(keys: string[]) => void	Callback when visible field keys change
onClearAll	() => void	Callback when user clears all filters
onImportCsv	() => void	Callback for CSV import action
onImportXls	() => void	Callback for XLS/XLSX import action
enableImportCsv	boolean	Shows the CSV import button in toolbar
enableImportXls	boolean	Shows the XLS/XLSX import button in toolbar

Filter Field Builder

Use filterField() builder to create filter field definitions with a fluent API:

import { filterField } from '@akinon/akifilter';

const field = filterField<FilterValues>()
  .key('fieldName')           // Field identifier (required)
  .type('text')               // Field type (required)
  .label('Field Label')       // Display label
  .placeholder('Placeholder') // Input placeholder
  .visible()                  // Show in main filter form by default
  .defaultValue('initial')    // Default value
  .build();

Field Types

Text Field

filterField<FilterValues>()
  .key('search')
  .type('text')
  .label('Search')
  .placeholder('Search...')
  .visible()
  .build()

Number Field

filterField<FilterValues>()
  .key('minPrice')
  .type('number')
  .label('Minimum Price')
  .placeholder('Enter amount')
  .visible()
  .build()

Select Field

filterField<FilterValues>()
  .key('category')
  .type('select')
  .label('Category')
  .placeholder('Select category')
  .options([
    { label: 'Electronics', value: 'electronics' },
    { label: 'Clothing', value: 'clothing' },
    { label: 'Books', value: 'books' }
  ])
  .visible()
  .build()

Date Field

filterField<FilterValues>()
  .key('createdAt')
  .type('date')
  .label('Created Date')
  .placeholder('Select date')
  .visible()
  .build()

Date with Time

filterField<FilterValues>()
  .key('scheduledAt')
  .type('date')
  .label('Scheduled At')
  .placeholder('Select date and time')
  .showTime(true)
  .visible()
  .build()

Checkbox Field

filterField<FilterValues>()
  .key('isActive')
  .type('checkbox')
  .label('Active Only')
  .visible()
  .build()

Textarea Field

filterField<FilterValues>()
  .key('description')
  .type('textarea')
  .label('Description')
  .placeholder('Enter description...')
  .build()

Custom Field

For advanced use cases, use custom fields with a render function:

filterField<FilterValues>()
  .key('customField')
  .type('custom')
  .label('Custom Filter')
  .render(({ field, control, formValues }) => (
    <MyCustomComponent
      control={control}
      name={field.key}
      formValues={formValues}
    />
  ))
  .visible()
  .build()

Field Visibility

By default, if no fields have explicit visibility set, the first 8 fields in the schema are shown. Use .visible() to explicitly mark which fields should appear in the main filter form:

// Explicitly visible
filterField<FilterValues>()
  .key('name')
  .type('text')
  .visible()  // Will always appear in main filter grid
  .build()

// No explicit visibility (uses default behavior)
filterField<FilterValues>()
  .key('advanced')
  .type('text')
  .build()  // Shown only if within first 8 fields, otherwise accessible via modal

If at least one field has .visible() set, only those explicitly marked fields will be shown by default. Otherwise, the first 8 fields are displayed.

Conditional Field Configuration

Fields can be dynamically disabled or hidden based on other field values:

interface FilterValues {
  type: string;
  subType: string;
}

const schema: AkifilterSchema<FilterValues> = [
  filterField<FilterValues>()
    .key('type')
    .type('select')
    .label('Type')
    .options([
      { label: 'Product', value: 'product' },
      { label: 'Service', value: 'service' }
    ])
    .visible()
    .build(),
  filterField<FilterValues>()
    .key('subType')
    .type('select')
    .label('Sub Type')
    .options([
      { label: 'Physical', value: 'physical' },
      { label: 'Digital', value: 'digital' }
    ])
    .visible()
    .config({
      // Disable when type is 'service'
      disabled: (formValues) => formValues.type === 'service',
      // Hide when type is empty
      visible: (formValues) => Boolean(formValues.type)
    })
    .build()
];

Section Fields

Group related filters into collapsible sections:

const schema: AkifilterSchema<FilterValues> = [
  // Regular fields
  filterField<FilterValues>()
    .key('name')
    .type('text')
    .label('Name')
    .visible()
    .build(),
  
  // Section with nested fields
  {
    key: 'advancedSection',
    type: 'section',
    label: 'Advanced Filters',
    fields: [
      filterField<FilterValues>()
        .key('minPrice')
        .type('number')
        .label('Min Price')
        .build(),
      filterField<FilterValues>()
        .key('maxPrice')
        .type('number')
        .label('Max Price')
        .build()
    ]
  }
];

Persistence

Akifilter automatically persists filter values and visibility settings to localStorage:

<Akifilter
  filterSchema={schema}
  storageNamespace="my-filters"  // Unique namespace for this filter instance
  onValuesChange={handleValuesChange}
/>

• Filter values are stored under appliedFilters-{namespace}

• Visibility settings are stored under shownFilters-{namespace}

• Values persist across page reloads

Applied Filters

Active filter values are displayed as removable chips above the filter form:

• Click the × on a chip to remove that filter

• Use "Clear All" to reset all filters to defaults

• Values are formatted based on field type (dates use locale format, booleans show Yes/No)

Visibility Modal

Users can customize which filters appear in the main form:

1. Click the "Select Filters" button in the toolbar

2. Search and paginate through available filters

3. Toggle checkboxes to show/hide filters

4. Selections are persisted to localStorage

Import Actions

Enable CSV/XLS import buttons for bulk filter operations:

<Akifilter
  filterSchema={schema}
  enableImportCsv
  enableImportXls
  onImportCsv={() => {
    // Handle CSV import
    console.log('Import CSV clicked');
  }}
  onImportXls={() => {
    // Handle XLS import
    console.log('Import XLS clicked');
  }}
  onValuesChange={handleValuesChange}
/>

Complete Example

import { Akifilter, filterField, type AkifilterSchema } from '@akinon/akifilter';

interface OrderFilters {
  orderNumber: string;
  status: string;
  customerName: string;
  minTotal: number | null;
  maxTotal: number | null;
  createdFrom: Date | null;
  createdTo: Date | null;
  isPaid: boolean;
}

const orderFilterSchema: AkifilterSchema<OrderFilters> = [
  filterField<OrderFilters>()
    .key('orderNumber')
    .type('text')
    .label('Order Number')
    .placeholder('Enter order number')
    .visible()
    .build(),
  filterField<OrderFilters>()
    .key('status')
    .type('select')
    .label('Status')
    .placeholder('Select status')
    .options([
      { label: 'Pending', value: 'pending' },
      { label: 'Processing', value: 'processing' },
      { label: 'Shipped', value: 'shipped' },
      { label: 'Delivered', value: 'delivered' },
      { label: 'Cancelled', value: 'cancelled' }
    ])
    .visible()
    .build(),
  filterField<OrderFilters>()
    .key('customerName')
    .type('text')
    .label('Customer Name')
    .placeholder('Search customer...')
    .visible()
    .build(),
  filterField<OrderFilters>()
    .key('isPaid')
    .type('checkbox')
    .label('Paid Orders Only')
    .visible()
    .build(),
  {
    key: 'priceRange',
    type: 'section',
    label: 'Price Range',
    fields: [
      filterField<OrderFilters>()
        .key('minTotal')
        .type('number')
        .label('Min Total')
        .placeholder('0')
        .build(),
      filterField<OrderFilters>()
        .key('maxTotal')
        .type('number')
        .label('Max Total')
        .placeholder('10000')
        .build()
    ]
  },
  {
    key: 'dateRange',
    type: 'section',
    label: 'Date Range',
    fields: [
      filterField<OrderFilters>()
        .key('createdFrom')
        .type('date')
        .label('From')
        .placeholder('Start date')
        .build(),
      filterField<OrderFilters>()
        .key('createdTo')
        .type('date')
        .label('To')
        .placeholder('End date')
        .build()
    ]
  }
];

export const OrderListFilters = () => {
  const handleValuesChange = (values: Partial<OrderFilters>) => {
    // Build query params and fetch orders
    const params = new URLSearchParams();
    
    Object.entries(values).forEach(([key, value]) => {
      if (value !== null && value !== undefined) {
        params.set(key, String(value));
      }
    });

    // fetchOrders(params);
  };

  const handleClearAll = () => {
    // Reset to initial state
  };

  return (
    <Akifilter
      filterSchema={orderFilterSchema}
      storageNamespace="order-list"
      onValuesChange={handleValuesChange}
      onClearAll={handleClearAll}
    />
  );
};

Internationalization

Akifilter uses @akinon/akilocale for built-in translations. Default labels and messages are provided in English and Turkish.

Best Practices

1. Define TypeScript interfaces - Always type your filter values for better type safety

2. Use meaningful storage namespaces - Prevents conflicts between different filter instances

3. Mark primary filters as visible - Show the most commonly used filters by default

4. Group related filters - Use section fields to organize complex filter sets

5. Handle empty states - Provide appropriate feedback when no filters are applied