# stringsArrayFilter

**Category:** Features/Filter/Factories

## Design

### Usage

The filter is used to manage an array of strings. The string value can be a simple string that is displayed to the user, an enum value that is translated using `itemName` prop, or even an array of IDs that is not used with UI component but rather as an internal filter for querying data.

**Do:**

- Use it for plain strings

- Use it for enum values

- Use it for IDs


**Don't:**

- Use it for complex data, prefer using idNameArrayFilter instead


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

### Array of strings

A simple array of strings with initial value.

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

function basicFilter() {
  const [filter] = React.useState(() =>
    stringsArrayFilter({ initialValue: ['Semi-Pro'] }),
  );

  return (
    <Layout>
      <Cell span={4}>
        <SingleSelectFilter
          filter={filter}
          data={[
            'Beginner',
            'Amateur',
            'Semi-Pro',
            'Professional',
            'World Class',
            'Legendary',
            'Ultimate',
          ]}
        />
      </Cell>
    </Layout>
  );
}
```

### Array of statuses

The `itemName` prop is used to convert an enum value, which represents the status, into a user-friendly value, usually with a translation.

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

function statusFilter() {
  const statusDisplayName = (status) => {
    switch (status) {
      case 'done':
        return 'Done';
      case 'in-progress':
        return 'In Progress';
      default:
        return 'Failed';
    }
  };

  const [filter] = React.useState(() =>
    stringsArrayFilter({ itemName: statusDisplayName }),
  );

  return (
    <Layout>
      <Cell span={4}>
        <SingleSelectFilter
          filter={filter}
          data={['done', 'in-progress', 'failed']}
        />
      </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 |