# idNameArrayFilter

**Category:** Features/Filter/Factories

## Design

### Usage

This filter is often used for complex objects and types that do not have official support in Wix Patterns.

The filter must have `id` and `name` attributes at minimum, but additional attributes can be included as needed. An example of an unsupported type that can be easily implemented with this filter is the boolean type as you will see below.

However, it is important to note that objects such as date range and plain strings do have official support and you should use the dedicated factories and not this factory.


**Do:**

- Use it for complex objects

- Use it for booleans


**Don't:**

- Use it for simple strings

- Use it for date range


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

### Basic

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

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

  const collection = useStaticListFilterCollection(
    filter,
    ['Option #1', 'Option #2', 'Option #3', 'Option #4', 'Option #5'].map(
      (name) => ({ id: name, name }),
    ),
  );

  return (
    <Layout>
      <Cell span={4}>
        <MultiSelectCheckboxFilter
          popoverProps={{ appendTo: 'window' }}
          filter={filter}
          collection={collection}
        />
      </Cell>
    </Layout>
  );
}
```

### Complex object with odd properties

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

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

  const collection = useStaticListFilterCollection(
    filter,
    [
      { foo: 'Option #1', bar: 'option-1' },
      { foo: 'Option #2', bar: 'option-2' },
      { foo: 'Option #3', bar: 'option-3' },
      { foo: 'Option #4', bar: 'option-4' },
      { foo: 'Option #5', bar: 'option-5' },
    ].map((item) => ({ id: item.bar, name: item.foo })),
  );

  return (
    <Layout>
      <Cell span={4}>
        <MultiSelectCheckboxFilter
          popoverProps={{ appendTo: 'window' }}
          filter={filter}
          collection={collection}
        />
      </Cell>
    </Layout>
  );
}
```

### Boolean support

During the `fetchData` method in the `Table` API, we save the necessary value for querying under the `value` property. This value can then be accessed using `filter.value` and passed to the filters object.

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

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

  const collection = useStaticListFilterCollection(filter, [
    { id: '1', name: 'Published', value: true },
    { id: '2', name: 'Not Published', value: false },
  ]);

  return (
    <Layout>
      <Cell span={4}>
        <SingleSelectFilter
          popoverProps={{ appendTo: 'window' }}
          filter={filter}
          collection={collection}
        />
      </Cell>
    </Layout>
  );
}
```

### Querying data with id and name as main properties

The response from the `/fake-entity` endpoint includes the `id` and `name` of the entity, so using the filter as-is is sufficient. All other properties are already assigned correctly.

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

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

  const fakeEntityHttpClient = useFakeEntityHttpClient();

  const collection = useFilterCollection(filter, {
    queryName: 'fakeEntity-filter',
    fetchData: (query) => {
      const { limit, offset } = query;
      return fakeEntityHttpClient
        .request({
          url: '/api/fake-entity',
          params: { limit, offset },
        })
        .then(({ data: { items, total } }) => ({ items, total }));
    },
    limit: 50,
    filters: {},
  });

  return (
    <Layout>
      <Cell span={4}>
        <MultiSelectCollectionFilter
          popoverProps={{ appendTo: 'window' }}
          filter={filter}
          collection={collection}
        />
      </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 |