Akifilter • Akinon UI Documentation

Overview

Akifilter component from the @akinon/akifilter package It is a customizable filter component for React applications and provides advanced filtering features.

Example Usage


import { Akifilter, type AkifilterSchema } from '@akinon/akifilter';
 
const filterSchema: AkifilterSchema = [
  {
    key: 'username',
    type: 'text',
    label: 'Username',
    placeholder: 'Enter username'
  },
  {
    key: 'status',
    type: 'select',
    label: 'Status',
    placeholder: 'Select status',
    options: [
      { value: 'active', label: 'Active' },
      { value: 'inactive', label: 'Inactive' }
    ]
  },
  {
    key: 'isActive',
    type: 'checkbox',
    label: 'Is Active'
  }
];
 
const MyComponent = () => {
  const handleValuesChange = (values: Record<string, unknown>) => {
    console.log('Filter values changed:', values);
    // Use values to fetch data, update URL params, etc.
  };
 
  return (
    <Akifilter
      filterSchema={filterSchema}
      storageNamespace="users-filter"
      onValuesChange={handleValuesChange}
      defaultValues={{ status: 'active' }}
    />
  );
};

Akifilter Props

Akifilter props provide various options for configuring the filter component:

Property	Description	Type	Default
`filterSchema`	Declarative description of the filter fields	`AkifilterSchema`	`[]`
`storageNamespace`	Optional namespace for local storage persistence. Filters are saved and restored automatically.	`string`	-
`defaultValues`	Default values supplied by the host application	`Partial<TFieldValues>`	-
`onValuesChange`	Callback fired on every filter value change with the normalised payload	`(values: Partial<T>) => void`	-
`onVisibleFieldsChange`	Callback fired whenever visible field keys change	`(keys: string[]) => void`	-
`onImportCsv`	Callback triggered when user clicks the CSV import button	`() => void`	-
`onImportXls`	Callback triggered when user clicks the XLS/XLSX import button	`() => void`	-
`onClearAll`	Callback triggered when user requests clearing all filters	`() => void`	-
`enableImportCsv`	Shows the CSV import button in the toolbar	`boolean`	`false`
`enableImportXls`	Shows the XLS/XLSX import button in the toolbar	`boolean`	`false`
`filterActionsRef`	Ref to access imperative filter actions like clearing specific filter values programmatically	`React.Ref<AkifilterActionsRef>`	-

Storage Behavior

When storageNamespace is provided, Akifilter automatically persists filter values and field visibility preferences to local storage:

Filter values are saved on change (debounced)
Visible field selections are saved when toggled
Values are restored on component mount
Storage key is generated based on schema structure and namespace

This enables users to maintain their filter preferences across sessions.

Field Configuration

Each field in filterSchema supports an optional config property that enables advanced control over field behavior:


const filterSchema: AkifilterSchema = [
  {
    key: 'status',
    type: 'select',
    label: 'Status',
    placeholder: 'Select status',
    options: [
      { value: 'active', label: 'Active' },
      { value: 'inactive', label: 'Inactive' }
    ],
    config: {
      disabled: true, // Field is disabled
      visible: true // Field is visible
    }
  }
];

config.disabled

Controls whether a filter field is disabled. Can be either:

Boolean: Static disable state


config: {
  disabled: true;
} // Field always disabled

Function: Dynamic disable state based on other field values


config: {
  disabled: formValues => !formValues.status; // Disable when status is empty
}

config.visible

Controls whether a filter field is displayed. Can be either:

Boolean: Static visibility state


config: {
  visible: false;
} // Field always hidden

Function: Dynamic visibility based on other field values


config: {
  visible: formValues => formValues.status === 'admin'; // Show only if admin status
}

Function with currentVisible: The callback receives an optional second parameter currentVisible (boolean | undefined) indicating whether the field is currently visible (based on the user’s field visibility selection). This allows you to combine dynamic logic with the user’s visibility preference.
```
config: {
  visible: (formValues, currentVisible) => {
    // Keep the field visible if the user has toggled it on,
    // otherwise show only when status is 'error'
    return currentVisible ?? formValues.status === 'error';
  };
}
```

Default Values Behavior

When using the filterSchema with defaultValue properties, note that:

defaultValue in schema: Used as the schema default value
defaultValues prop: Passed as initial values to the filter form
Clear All action: Resets fields to schema defaultValue only (not external defaultValues)

This allows distinction between schema-defined defaults and external initial values. When clearing filters, only the schema-defined defaults are applied.


import { Akifilter, type AkifilterSchema } from '@akinon/akifilter';
 
const filterSchema: AkifilterSchema = [
  {
    key: 'region',
    type: 'select',
    label: 'Region',
    placeholder: 'Select region',
    defaultValue: 'all', // Schema default - used on clear
    options: [
      { value: 'all', label: 'All Regions' },
      { value: 'eu', label: 'Europe' },
      { value: 'us', label: 'United States' }
    ]
  }
];
 
const MyComponent = () => {
  return (
    <Akifilter
      filterSchema={filterSchema}
      storageNamespace="products-filter"
      defaultValues={{ region: 'eu' }} // Shows 'Europe' initially
      onValuesChange={values => console.log('Values:', values)}
    />
  );
};
 
// When user clicks "Clear All", region resets to 'all' (schema default)
// NOT to 'eu' (external defaultValues)

Date Field with Time

Date fields support the showTime property to include time selection:


const filterSchema: AkifilterSchema = [
  {
    key: 'createdDate',
    type: 'date',
    label: 'Created Date',
    showTime: true // Includes time picker
  }
];

When showTime is enabled, the applied filter displays both date and time in localized format.

Custom Field Options

Custom fields (type: 'custom') can include an optional options array. This array is not used for rendering — the render function handles the UI. Instead, Akifilter uses it to resolve selected values into human-readable labels in the applied filters bar. This works for both single and multi-select values.


const filterSchema: AkifilterSchema = [
  {
    key: 'category',
    type: 'custom',
    label: 'Category',
    options: [
      { value: 'electronics', label: 'Electronics' },
      { value: 'clothing', label: 'Clothing' },
      { value: 'books', label: 'Books' }
    ],
    render: ({ field, formValues, control }) => (
      <MyCustomSelect field={field} formValues={formValues} control={control} />
    )
  }
];
 
// Single value: applied filter shows "Electronics" instead of "electronics"
// Multi-select value: applied filter shows "Electronics, Clothing" instead of "electronics,clothing"

Without options, applied filter chips display raw values. With options, labels are resolved automatically for both single values and arrays.

Imperative Actions with filterActionsRef

The filterActionsRef prop provides imperative control over filter values, allowing you to programmatically clear specific fields from outside the component:


import { useRef } from 'react';
import {
  Akifilter,
  type AkifilterActionsRef,
  type AkifilterSchema
} from '@akinon/akifilter';
import { Button } from '@akinon/ui-button';
 
const filterSchema: AkifilterSchema = [
  {
    key: 'orderNo',
    type: 'text',
    label: 'Order No',
    placeholder: 'Enter order number'
  },
  {
    key: 'customerName',
    type: 'text',
    label: 'Customer Name',
    placeholder: 'Enter customer name'
  },
  {
    key: 'status',
    type: 'select',
    label: 'Status',
    options: [
      { value: 'pending', label: 'Pending' },
      { value: 'completed', label: 'Completed' }
    ]
  }
];
 
const MyComponent = () => {
  const filterActionsRef = useRef<AkifilterActionsRef>(null);
 
  const handleClearOrderNo = () => {
    // Clear a single field
    filterActionsRef.current?.clearValue('orderNo');
  };
 
  const handleClearMultiple = () => {
    // Clear multiple fields at once
    filterActionsRef.current?.clearValue(['customerName', 'status']);
  };
 
  return (
    <div>
      <div style={{ marginBottom: 16, display: 'flex', gap: 8 }}>
        <Button onClick={handleClearOrderNo}>Clear Order No</Button>
        <Button onClick={handleClearMultiple}>
          Clear Customer Name & Status
        </Button>
      </div>
      <Akifilter
        filterSchema={filterSchema}
        filterActionsRef={filterActionsRef}
        onValuesChange={values => console.log('Values changed:', values)}
      />
    </div>
  );
};

AkifilterActionsRef API

Method	Parameters	Description
`clearValue`	`keys: string \| string[]`	Clears the value of one or more filter fields by their key(s)

Import Actions

Akifilter supports optional CSV and XLS/XLSX import buttons in the toolbar. These are hidden by default and can be enabled via props:


import { Akifilter, type AkifilterSchema } from '@akinon/akifilter';
 
const filterSchema: AkifilterSchema = [
  {
    key: 'productId',
    type: 'text',
    label: 'Product ID'
  }
];
 
const MyComponent = () => {
  const handleImportCsv = () => {
    // Implement CSV import logic
    console.log('Import from CSV');
  };
 
  const handleImportXls = () => {
    // Implement XLS/XLSX import logic
    console.log('Import from XLS/XLSX');
  };
 
  return (
    <Akifilter
      filterSchema={filterSchema}
      enableImportCsv={true}
      enableImportXls={true}
      onImportCsv={handleImportCsv}
      onImportXls={handleImportXls}
      onValuesChange={values => console.log('Values:', values)}
    />
  );
};

When enabled, import buttons appear in the filter toolbar, allowing users to trigger custom import workflows.

Additional Callbacks

onClearAll

Triggered when the user clicks the “Clear All” button:


<Akifilter
  filterSchema={filterSchema}
  onClearAll={() => {
    console.log('All filters cleared');
    // Perform additional cleanup if needed
  }}
  onValuesChange={values => console.log('Values:', values)}
/>

onVisibleFieldsChange

Triggered when the user changes which fields are visible in the filter:


<Akifilter
  filterSchema={filterSchema}
  onVisibleFieldsChange={visibleKeys => {
    console.log('Visible fields:', visibleKeys);
    // Track user preferences or analytics
  }}
  onValuesChange={values => console.log('Values:', values)}
/>