@wix/patterns 1.366.0 → 1.370.0

package/dist/docs/bulkActionModal.md

@@ -0,0 +1,40 @@
+# bulkActionModal
+
+**Category:** Features/Actions/Bulk Actions
+
+## API
+
+### Overview
+
+`bulkActionModal` is a render-prop passed to collection components (`Table`, `Grid`, `TableFolders`, etc.) that opens a custom modal when a bulk action is triggered from the [`MultiBulkActionToolbar`](./?path=/story/features-actions-bulk-actions--multibulkactiontoolbar).
+
+The render function receives:
+- `selectedValues` — the items selected via the checkbox column
+- `uncheckedValues` — the items that were unchecked (relevant when "Select All" is active)
+- `isSelectAll` — whether the "Select All" checkbox is checked
+- `closeModal` — closes the modal
+- `query` — a [`ComputedQuery`](./?path=/story/common-types--computedquery) representing the current paging, sorting, and filtering. Useful for server-side bulk operations like `updateAll` or `deleteAll`.
+
+Return a React element (typically a `` or custom modal content) from the render function.
+
+### Usage
+
+```tsx
+ (
+    
+      
+        Delete Selected
+      
+    
+  )}
+  bulkActionModal={({ selectedValues, closeModal }) => (
+     { deleteItems(selectedValues); closeModal(); }}
+      secondaryButtonText="Cancel"
+      secondaryButtonOnClick={closeModal}
+    >
+      Delete {selectedValues.length} items?
+    
+  )}
+/>
+```
+

package/dist/docs/createNestedTableLevel.md

@@ -0,0 +1,24 @@
+# createNestedTableLevel
+
+**Category:** Base Components/Collections/NestedTable
+
+## API
+
+### Overview
+
+A helper function that creates a [`NestedTableLevel`](./?path=/story/base-components-collections-nestedtable--nestedtablelevel) descriptor without specifying `depth` (depth is assigned automatically based on array position). Pass the result to the `levels` array in [`useNestedTable`](./?path=/story/base-components-collections-nestedtable-usenestedtable--usenestedtable).
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `actionCell` | `ActionCell<T, F>` | No | - | A table's last column. Use this column to add an action at the end of each row. For example, a delete button to delete an item. Pass an [`ActionCellProps`](https://www.docs.wixdesignsystem.com/?path=/story/components-lists-table--tableactioncell) object, or a function that returns an `ActionCellProps` object. |
+| `columns` | `Partial<Record<C, (row: T, rowNum: number) => ReactNode>>` | No | - | Render logic of the cells for this level. By default, all cells will be empty |
+| `isRowHighlight` | `((item: T) => boolean)` | No | - | A function that accepts the item of the current level and returns a boolean value indicating whether the item should be highlighted. |
+| `renderMainColumn` | `RenderMainColumn<T>` | No | - | Render logic of the main column for this level. T) => { title?: string; subtitle?: string; image?: ReactNode; } |
+| `breadcrumbs` | `((item: T) => { id: string; name: string; }[] \| null)` | No | - | A function that accepts the item of the current level and returns an array of breadcrumbs to be displayed in the toolbar. Each breadcrumb is an object with `id` and `name` properties. `fetchData` will be called with `query.fields` that contains the value `breadcrumbs` to signal that the breadcrumbs should be fetched. |
+| `expandable` | `((item: T) => boolean)` | No | - | A function that accepts the item of the current level and returns a boolean value that indicates whether the item can be expanded. By default, all items are expandable. |
+| `parentKey` | `(item: T) => string \| null \| undefined` | Yes | - | A function that accepts the item of the current level and returns the key of the parent item, for example: `(item) => item.parentId`. |
+| `createCollection` | `(params?: NestedOptimisticActionsState<T, F> \| undefined) => { collection: CollectionState<T, F>; parentFilter?: Filter<...> \| undefined; }` | Yes | - | A function that creates a collection for the current level (using [useCreateCollection](./?path=/story/common-hooks--usecreatecollection) hook), and returns the collection state and a reference to a filter object within this collection that filters the collection by the parent key. => { collection: [CollectionState](./?path=/story/common-state--collectionstate); parentFilter?: [Filter<string[]>](./?path=/story/features-filter-factories--stringsarrayfilter); } |
+| `optimisticActionsPredicate` | `((query: ComputedQuery<F>) => (item: T) => boolean)` | No | - | A [predicate](./?path=/story/features-actions-updates--useoptimisticactions) function to pass to the internal [OptimisticActions](/?path=/story/features-actions-updates--collectionoptimisticactions) created by NestedTable |
+

package/dist/docs/createNestedTableSingleEntityLevels.md

@@ -0,0 +1,20 @@
+# createNestedTableSingleEntityLevels
+
+**Category:** Base Components/Collections/NestedTable
+
+## API
+
+### Overview
+
+A helper function to create multiple nested table levels out of the same configurations for a single entity type.
+
+It's the same as [createNestedTableLevel](./?path=/story/base-components-collections-nestedtable--createnestedtablelevel) for cases where all levels are of the same entity type.
+
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `count` | `number` | Yes | - | Number of levels to create |
+| `config` | `Omit<NestedTableLevelDescriptor<C, T, F>, "depth">` | No | - | Configuration for all levels |
+

package/dist/docs/customFilter.md

@@ -0,0 +1,182 @@
+# customFilter
+
+**Category:** Features/Filter/Factories
+
+## Design
+
+### Usage
+
+A generic filter factory to be passed to [useCollection](./?path=/story/common-hooks--usecollection) `filters` property. This factory, allows creating custom filters that are not provided by Wix Patterns.
+
+To create a custom filter, we must implement 2 different parts:
+
+- A filter state - using `customFilter` factory (see example below).
+- A filter component - our component must accept a `filter` prop and be wrapped with `observer` (see example below).
+
+
+**Do:**
+
+- Use it only when you must create a custom filter component
+
+- Use it after consulting with WixPatterns team
+
+
+**Don't:**
+
+- Use it without updating WixPatterns team
+
+
+```tsx
+import { customFilter } from '@wix/patterns';
+```
+
+### Custom date filter component
+
+An example of creating a custom date filter component, though in practice it is recommended to use the pre-built [DateRangeFilter](./?path=/story/features-filter-components--daterangefilter) component instead.
+
+```tsx
+import { Avatar, DatePicker } from '@wix/design-system';
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  CollectionToolbarFilters,
+  customFilter,
+  Table,
+  observer,
+  useTableCollection,
+  Filter,
+  OffsetQuery,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+import { addDays } from 'date-fns';
+
+type ContactsFilters = {
+  lastActivity: Filter<Date>;
+};
+
+function customFilterExample() {
+  // Part 1 - Implement the filter state.
+  const [lastActivityDate] = React.useState(() =>
+    customFilter<Date | null>({
+      defaultValue: null,
+      isEmpty: (date) => date == null,
+      toArray: (date) => [date],
+      itemKey: (date) => date?.toISOString() ?? '',
+      itemName: (date) => date?.toLocaleDateString() ?? '',
+      toQueryString: (date) => date?.toISOString() ?? '',
+      fromQueryString: (str) => (str ? new window.Date(str) : null),
+      encode: (date) => date?.toISOString(),
+      decode: (str) => (typeof str === 'string' ? new Date(str) : null),
+    }),
+  );
+
+  // Part 2 - Implement the filter component.
+  const [CustomDateFilter] = React.useState(() =>
+    // Our custom component must accept a `filter` prop and be wrapped with `observer`
+    observer(function DateFilter({ filter }: { filter: Filter<Date> }) {
+      return (
+        <DatePicker
+          popoverProps={{ appendTo: 'window' }}
+          value={filter.value}
+          onChange={(date: Date) => filter.refresh(date)}
+        />
+      );
+    }),
+  );
+
+  const state = useTableCollection<contacts.Contact, ContactsFilters>({
+    queryName: 'CustomFilterExample',
+    fetchData: (query: OffsetQuery<ContactsFilters>) => {
+      const { limit, offset, search, filters } = query;
+
+      let queryBuilder = contacts.queryContacts().limit(limit).skip(offset);
+
+      if (search) {
+        queryBuilder = queryBuilder.startsWith('info.name.first', search);
+      }
+
+      if (filters.lastActivity) {
+        queryBuilder = queryBuilder
+          .gt('lastActivity.activityDate', filters.lastActivity)
+          .lt('lastActivity.activityDate', addDays(filters.lastActivity, 1));
+      }
+
+      return queryBuilder.find().then(({ items = [], totalCount: total }) => ({
+        items,
+        total,
+      }));
+    },
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchErrorMessage: () => 'Error fetching contacts',
+    filters: {
+      lastActivity: lastActivityDate as Filter<Date>,
+    },
+  });
+
+  const collection = state.collection;
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Table
+          state={collection}
+          columns={[
+            {
+              title: '',
+              width: '50px',
+              render: (contact) => (
+                <Avatar
+                  name={`${contact.info?.name?.first} ${contact.info?.name?.last}`}
+                  imgProps={{ src: contact.info?.picture?.image }}
+                />
+              ),
+            },
+            {
+              title: 'Name',
+              width: '250px',
+              render: (contact) =>
+                `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+            },
+            {
+              title: 'Last Activity',
+              render: (contact) =>
+                contact.lastActivity?.activityDate?.toLocaleString(),
+            },
+          ]}
+          filters={
+            <CollectionToolbarFilters>
+              <CustomDateFilter filter={collection.filters.lastActivity} />
+            </CollectionToolbarFilters>
+          }
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `defaultValue` | `T` | Yes | - | The value to set the value to, when clearing the filter. |
+| `isEmpty` | `(value: T) => boolean` | Yes | - | Indicates whether nothing is selected.<br> For example, when implementing a range filter, when both minimum and maximum inputs are empty |
+| `size` | `((value: T) => number)` | No | `A function that 0 when `isEmpty` returns true, and 1 otherwise.` | Indicates the number of effective filters.<br> For example, when implementing a range filter, 1 when only minimum/maximum are entered, 2 - when both entered. |
+| `toQueryString` | `((value: T) => string)` | No | - | Convert the filter value to a string, to be stored in a URL. |
+| `fromQueryString` | `((str: string) => T)` | No | - | Convert the a string value to the filter value, to be retrieved from a URL. |
+| `decode` | `(value: unknown) => T` | 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 |
+| `encode` | `(value: T) => unknown` | Yes | - | Return a simplified form of an item for serialization. @param value |
+| `toArray` | `(value: T) => FilterItem<T>[]` | Yes | - | Flatten the correct selection to an array, to be shown in the table sub-toolbar in a tag list. Usually this will return an array with a single item, but it gives control when we want to show more than a 1 tag in the tag list. |
+| `remove` | `((item: FilterItem<T>[], value: T) => T)` | No | `A function that returns `defaultValue`.` | Remove a tag from the tag list. |
+| `hasDiff` | `((data: T) => boolean)` | No | - | Indicates whether current filter value is different than `data` |
+| `matches` | `((item: FilterItem<T>, value: T) => boolean)` | No | - | Indicates whether an item matches the current value of the filter |
+| `equals` | `((item1: FilterItem<T>, item2: FilterItem<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: FilterItem<T>) => string` | Yes | - | A callback function that accepts an item and returns a unique ID of it. typically `item.id`. |
+| `itemName` | `(item: FilterItem<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 |
+

package/dist/docs/dateRangeFilter.md

@@ -0,0 +1,55 @@
+# dateRangeFilter
+
+**Category:** Features/Filter/Factories
+
+## Design
+
+### Usage
+
+The filter is used together with [DateRangeFilter](./?path=/story/features-filter-components--daterangefilter) component. Check the component examples section to see all possibilities for this filter.
+
+**Do:**
+
+- Use with DateRangeFilter component
+
+
+**Don't:**
+
+- Use with other filter components
+
+
+```tsx
+import { dateRangeFilter } from '@wix/patterns';
+```
+
+### Basic
+
+```tsx
+import React from 'react';
+import { dateRangeFilter, DateRangeFilter } from '@wix/patterns';
+
+function dateRangeFilterExample() {
+  const [filter] = React.useState(() => dateRangeFilter());
+
+  return <DateRangeFilter filter={filter} />;
+}
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `parse` | `((value: unknown) => Date \| null)` | No | - | Convert an unknown object to a T. @param value |
+| `simplify` | `((value: Date) => Partial<Date>)` | No | - | Return a simplified form of an item for serialization. @param value |
+| `matches` | `((item: RangeItem<Date>, value: RangeItem<Date>) => boolean)` | No | - | Indicates whether an item matches the current value of the filter |
+| `isEmptyPreset` | `((preset?: string) => boolean)` | No | - | Indicates whether a preset does not exist or is empty |
+| `parsePreset` | `((preset?: string) => RangeItem<Date>)` | No | - | Converts a preset string to a RangeItem @param preset |
+| `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` | `RangeItem<Date>` | No | - | The value to initialize the filter with (Optional) |
+| `itemKey` | `((item: RangeItem<Date>) => string)` | No | - | A callback function that accepts an item and returns a unique ID of it. typically `item.id`. |
+| `itemName` | `((item: RangeItem<Date>) => string)` | No | - | A callback function that accepts an item and returns the item name which is used in many messages through cairo |
+| `equals` | `((item1: RangeItem<Date>, item2: RangeItem<Date>) => boolean)` | No | - | A function which accepts 2 items and returns true if they are equal |
+| `isCustomField` | `boolean` | No | - | If the filter is a custom field |
+

package/dist/docs/deleteSecondaryAction.md

@@ -0,0 +1,122 @@
+# deleteSecondaryAction
+
+**Category:** Features/Actions/Action Cell
+
+## Design
+
+### Demo
+
+This example uses `deleteSecondaryAction()` to add a delete action under a popover menu in the last column of the table.
+
+```tsx
+import { Avatar, Page } from '@wix/design-system';
+import React from 'react';
+import {
+  deleteSecondaryAction,
+  Table,
+  PageWrapper,
+  OffsetQuery,
+  useCollection,
+  useOptimisticActions,
+  ToolbarTitle,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+function DeleteSecondaryAction() {
+  const collection = useCollection<contacts.Contact>({
+    queryName: 'contacts-DeleteSecondaryAction',
+    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',
+    filters: {},
+  });
+
+  const optimisticActions = useOptimisticActions(collection);
+
+  return (
+    <PageWrapper>
+      <Page height="400px">
+        <Page.Content>
+          <Table
+            state={collection}
+            title={<ToolbarTitle title="Contacts" showTotal />}
+            columns={[
+              {
+                title: '',
+                width: '50px',
+                render: (contact) => (
+                  <Avatar
+                    name={`${contact.info?.name?.first} ${contact.info?.name?.last}`}
+                    imgProps={{ src: contact.info?.picture?.image }}
+                  />
+                ),
+              },
+              {
+                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(),
+              },
+            ]}
+            actionCell={(_contact, _index, actionCellAPI) => ({
+              secondaryActions: [
+                deleteSecondaryAction({
+                  optimisticActions,
+                  actionCellAPI,
+                  submit: (_contacts) =>
+                    Promise.all(
+                      _contacts.map((contact) =>
+                        contacts.deleteContact(contact._id as string),
+                      ),
+                    ),
+                }),
+              ],
+            })}
+          />
+        </Page.Content>
+      </Page>
+    </PageWrapper>
+  );
+}
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `optimisticActions` | `CollectionOptimisticActions<T, F>` | Yes | - | Actions for performing optimistic updates on the collection. These updates are applied immediately for better user experience while waiting for the server response. |
+| `actionCellAPI` | `ActionCellAPI<T, F>` | Yes | - | API for interacting with the action cell. This API provides methods for manipulating and accessing the action cell's state. |
+| `submit` | `(items: T[]) => Promise<R>` | Yes | - | Function to submit the deletion operation. @param items - The items to delete. |
+| `showUndoToast` | `boolean` | No | `false` | Determines whether to display an undo toast before calling the server action. |
+| `showUndoSuccessToast` | `boolean` | No | `false` | Determines whether to display a toast after clicking on undo. |
+| `onUndo` | `(() => void)` | No | - | Callback function triggered when the user clicks on the undo button. |
+| `errorToast` | `((err: unknown, params: { retry: () => void; }) => string \| ToastConfig)` | No | - | Function to generate error toast to show in case the server fails to perform the action. |
+| `onError` | `((err: unknown) => void)` | No | - | Callback function triggered when an error occurs. |
+| `onTryAgain` | `(() => void \| Promise<void>)` | No | - | Callback function to retry the action. @deprecated Use the prop `errorToast={(err, {retry}) => { action:{onClick: () {retry();} }}}` instead. |
+| `successToast` | `string \| ToastConfig` | No | - | Toast message or configuration to show on successful action. |
+| `updateServerAfter` | `EventuallyUpdated` | No | `submit` | Indicates when the server is eventually updated. Possible values: - submit: Server updates immediately after the submission promise resolves. - number: Server updates after a specified timeout (in milliseconds). - Promise: Server updates after a forwarded promise resolves. |
+

package/dist/docs/idNameArrayFilter.md

@@ -0,0 +1,206 @@
+# 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 |
+