# arrayFilter

**Category:** Features/Filter/Factories

## Design

### Description

A generic filter factory that can be used with the `filters` property of the `useCollection` hook, for selecting one or multiple values from a fixed or dynamic list of items.

This is the base factory for the existing factories that we have:

- [idNameArrayFilter](./?path=/story/features-filter-factories--idnamearrayfilter)
- [stringsArrayFilter](./?path=/story/features-filter-factories--stringsarrayfilter)


```tsx
import { arrayFilter } from '@wix/patterns';
```

**Do:**

- Use it when existing factories don't answer your use-case


**Don't:**

- Use it to re-implement already existing factories


### stringArrayFilter

A reproduce of `stringsArrayFilter`.

```tsx
import React from 'react';
import {
  stringsArrayFilter,
  SingleSelectFilter,
  useStaticListFilterCollection,
} from '@wix/patterns';
import { Cell, Layout } from '@wix/design-system';

function stringArrayFilterExample() {
  const [filter] = React.useState(() =>
    stringsArrayFilter({
      itemKey: (item) => `item-${item}`,
      itemName: (item) => item,
    }),
  );

  const levelsCollection = useStaticListFilterCollection(filter, [
    'Beginner',
    'Amateur',
    'Semi-Pro',
    'Professional',
    'World Class',
    'Legendary',
    'Ultimate',
  ]);

  return (
    <Layout>
      <Cell span={4}>
        <SingleSelectFilter filter={filter} collection={levelsCollection} />
      </Cell>
    </Layout>
  );
}
```

### idNameArrayFilter

A reproduce of `idNameArrayFilter`.

```tsx
import React from 'react';
import {
  idNameArrayFilter,
  SingleSelectFilter,
  useStaticListFilterCollection,
} from '@wix/patterns';
import { Cell, Layout } from '@wix/design-system';

interface Level {
  id: string;
  name: string;
}

function idNameArrayFilterExample() {
  const [filter] = React.useState(() => idNameArrayFilter());

  const levelsCollection = useStaticListFilterCollection(filter, [
    { id: 'b', name: 'Beginner' },
    { id: 'a', name: 'Amateur' },
    { id: 's', name: 'Semi-Pro' },
    { id: 'p', name: 'Professional' },
    { id: 'w', name: 'World Class' },
    { id: 'l', name: 'Legendary' },
    { id: 'u', name: 'Ultimate' },
  ]);

  return (
    <Layout>
      <Cell span={4}>
        <SingleSelectFilter filter={filter} collection={levelsCollection} />
      </Cell>
    </Layout>
  );
}
```

### Custom array of objects

A reproduce of `stringsArrayFilter`.

```tsx
import React from 'react';
import {
  arrayFilter,
  MultiSelectCheckboxFilter,
  useStaticListFilterCollection,
} from '@wix/patterns';
import { Avatar, Cell, Layout } from '@wix/design-system';

interface City {
  id: string;
  title: string;
  subtitle: string;
  description: string;
  imageUrl: string;
}

function customArrayFilter() {
  const [filter] = React.useState(() =>
    arrayFilter<City>({
      itemKey: (item) => item.id,
      itemName: (item) => item.title,
      parse: (value) =>
        typeof value === 'object' && value
          ? {
              id: value.id as string,
              title: value.title as string,
              subtitle: value.subtitle as string,
              description: value.description as string,
              imageUrl: value.imageUrl as string,
            }
          : null,
    }),
  );

  const citiesCollection = useStaticListFilterCollection(filter, [
    {
      id: '1',
      title: 'Jerusalem',
      subtitle: 'Israel',
      description: 'Fascinating place to visit and photograph',
      imageUrl: `https://www.planetware.com/wpimages/2019/12/israel-in-pictures-beautiful-places-to-photograph-jerusalem.jpg`,
    },
    {
      id: '2',
      title: 'The Dead Sea',
      subtitle: 'Israel',
      description: 'The lowest land point on Earth',
      imageUrl: `https://www.planetware.com/wpimages/2019/12/israel-in-pictures-beautiful-places-to-photograph-the-dead-sea.jpg`,
    },
    {
      id: '3',
      title: 'Masada',
      subtitle: 'Israel',
      description: 'Mountaintop fortress',
      imageUrl: `https://www.planetware.com/wpimages/2019/12/israel-in-pictures-beautiful-places-to-photograph-masada.jpg`,
    },
    {
      id: '4',
      title: 'Eilat',
      subtitle: 'Israel',
      description: 'Southern Israeli city',
      imageUrl: `https://www.planetware.com/wpimages/2019/12/israel-in-pictures-beautiful-places-to-photograph-eilat.jpg`,
    },
    {
      id: '5',
      title: 'Haifa',
      subtitle: 'Israel',
      description: "Israel's third largest city",
      imageUrl: `https://www.planetware.com/wpimages/2019/12/israel-in-pictures-beautiful-places-to-photograph-haifa.jpg`,
    },
  ]);

  return (
    <Layout>
      <Cell span={4}>
        <MultiSelectCheckboxFilter
          popoverProps={{ appendTo: 'window' }}
          filter={filter}
          collection={citiesCollection}
          renderItem={(item) => ({
            id: item.id,
            prefix: <Avatar size="size30" imgProps={{ src: item.imageUrl }} />,
            title: item.title,
            subtitle: item.description,
          })}
        />
      </Cell>
    </Layout>
  );
}
```

## API

### Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `defaultValue` | `T[]` | No | - | The value to set the value to, when clearing the filter (Optional) |
| `parse` | `(value: string \| Record<string, unknown> \| null \| undefined) => T \| null` | Yes | - | Convert a unknown object to a T.<br> If the function returns null, the item will be skipped when we try to deserializate it from an array. @param value |
| `simplify` | `((value: T) => Partial<T>)` | No | - | Return a simplified form of an item for serialization. @param value |
| `matches` | `((item: T, value: T[]) => boolean)` | No | - | Indicates whether an item matches the current value of the filter |
| `equals` | `((item1: T, item2: T) => boolean)` | No | - | A function which accepts 2 items and returns true if they are equal |
| `persistent` | `boolean` | No | - | Marks the filter as a "context" or "scope" filter. This makes the filter not be visible in the sub-toolbar tag list, not saved in views, not counted as "X filters applied". |
| `initialValue` | `T[]` | No | - | The value to initialize the filter with (Optional) |
| `itemKey` | `(item: T) => string` | Yes | - | A callback function that accepts an item and returns a unique ID of it. typically `item.id`. |
| `itemName` | `(item: T) => string` | Yes | - | A callback function that accepts an item and returns the item name which is used in many messages through cairo |
| `isCustomField` | `boolean` | No | - | If the filter is a custom field |