# stringFilter

**Category:** Features/Filter/Factories

## Design

### Usage

This filter was primarily designed to be used in conjunction with the search functionality within the WixPatterns collection. It is not typically necessary to use this filter instead of the other available filters.

**Do:**

- Use it to override search property in useCollection API

- Use it when you want to pass a single string value to query object


**Don't:**

- Use it in other use-cases unless suggested otherwise


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

### Set search input initial value

```tsx
import React from 'react';
import { CollectionPage } from '@wix/patterns/page';
import {
  Table,
  stringFilter,
  useTableCollection,
  OffsetQuery,
} from '@wix/patterns';
import { contacts } from '@wix/crm';

function ContactsTable() {

  const someInitialSearchParam = 'jo';

  const state = useTableCollection<contacts.Contact>({
    search: stringFilter({ initialValue: someInitialSearchParam }),
    queryName: 'contacts-CairoTable',
    fetchData: (query: OffsetQuery) => {
      const { limit, offset, search, filters } = query;

      let queryBuilder = contacts.queryContacts().limit(limit).skip(offset);

      if (search) {
        queryBuilder = queryBuilder.startsWith('info.name.first', search);
      }

      return queryBuilder.find().then(({ items = [], totalCount: total }) => ({
        items,
        total,
      }));
    },
    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
    fetchErrorMessage: () => 'Error Fetching Contacts',
  });

  return (
    <CollectionPage height="400px">
      <CollectionPage.Header title={{ text: 'Contacts' }} />
      <CollectionPage.Content>
        <Table
          state={state}
          columns={[
            {
              title: 'Name',
              width: '250px',
              render: (contact) =>
                `${contact.info?.name?.first} ${contact.info?.name?.last}`,
            },
            {
              title: 'Level',
              render: (contact) => contact.info?.jobTitle,
            },
          ]}
        />
      </CollectionPage.Content>
    </CollectionPage>
  );
}
```

### Set internal filter with single string value

This example shows how to use an internal single value as a filter when you have an external source change, such as when using a `BrowserRouter` or simple `setState`, and you need to refresh the collection. Examine the code to gain a better understanding of this example.

```tsx
import { Dropdown, FormField, Box } from '@wix/design-system';
import React from 'react';
import { CollectionPage } from '@wix/patterns/page';
import {
  Filter,
  OffsetQuery,
  Table,
  stringFilter,
  useTableCollection,
} from '@wix/patterns';
import { contacts } from '@wix/crm';

type ContactsFilters = {
  level: Filter<string>;
};

function ContactsTable() {

  const state = useTableCollection<contacts.Contact, ContactsFilters>({
    queryName: 'files-list',
    fetchData: (query: OffsetQuery<ContactsFilters>) => {
      const { limit, offset, search, sort, filters } = query;

      let queryBuilder = contacts.queryContacts().limit(limit).skip(offset);

      if (search) {
        queryBuilder = queryBuilder.startsWith('info.name.first', search);
      }

      if (filters.level) {
        queryBuilder = queryBuilder.in('info.jobTitle', [filters.level]);
      }

      return queryBuilder.find().then(({ items = [], totalCount: total }) => ({
        items,
        total,
      }));
    },
    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
    fetchErrorMessage: () => 'Error Fetching Contacts',
    filters: {
      level: stringFilter(),
    },
  });

  const collection = state.collection;

  return (
    <CollectionPage height="400px">
      <CollectionPage.Header title={{ text: 'Contacts' }} />
      <CollectionPage.Content>
        <Box paddingBottom="SP3">
          <FormField label="Level (As an external Input)">
            <Dropdown
              size="medium"
              placeholder="Select level"
              popoverProps={{ appendTo: 'window' }}
              options={[
                { id: 'Beginner', value: 'Beginner' },
                { id: 'Amateur', value: 'Amateur' },
                { id: 'Semi-Pro', value: 'Semi-Pro' },
                { id: 'Professional', value: 'Professional' },
                { id: 'World Class', value: 'World Class' },
                { id: 'Legendary', value: 'Legendary' },
                { id: 'Ultimate', value: 'Ultimate' },
              ]}
              onSelect={(e) => {
                /*
                  On level change, refresh the collection with new level value
                */
                collection.filters.level.refresh(e.id as string);
              }}
            />
          </FormField>
        </Box>
        <Table
          state={state}
          columns={[
            {
              title: 'Name',
              width: '250px',
              render: (contact) =>
                `${contact.info?.name?.first} ${contact.info?.name?.last}`,
            },
            {
              title: 'Level',
              render: (contact) => contact.info?.jobTitle,
            },
            {
              title: 'Last Activity',
              render: (contact) =>
                contact.lastActivity?.activityDate?.toLocaleString(),
            },
          ]}
        />
      </CollectionPage.Content>
    </CollectionPage>
  );
}
```

## API

### Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `initialValue` | `string` | No | - | The value to initialize the filter with (Optional) |
| `defaultValue` | `string` | No | - | The value to set the value to, when clearing the filter (Optional) |