# Filter List

<!-- meta: type=filter-list; location=Logic; category=Logic; platforms=Joomla and WordPress (where applicable) -->

## Overview

Filter List is a **Logic** in **Logic**. Keeps or removes list items whose field matches your criteria.

This step executes when the flow reaches it along a wired path. It does not call external services by itself unless combined with API or CMS steps — it shapes *how* the flow continues.

## Why use this node

Filter List is a **logic step** in the **Logic** group. Logic steps control how data moves through the flow: branch on conditions, loop over lists, pause, merge parallel paths, or reshape payloads.

Typical reasons teams add **Filter List** to a flow:

- Control flow structure around filter list in complex multi-step workflows
- Combine with triggers and action steps to replace bespoke integration scripts
- Make branching, looping, or timing explicit and testable in the designer

## Example workflows

Common patterns on the canvas:

1. **Trigger** → **Filter List** → **Send Email** / **API REST POST**
2. Parallel branches → **Merge** → **Filter List** → downstream action

## How to set it up

On Design, pick the list path, the field on each item to test (leave blank to test the whole item), match mode, operator, and value. Use comma or newline for “in list” values.

## Good to know

Outputs filtered_items (array), filtered_count, and original_count. When a list path is set, Available Fields also exposes filtered_items.0.* (first match) for drag-and-drop.

## Properties panel

The designer shows these tabs for this node:

| Tab | Purpose |
|-----|---------|
| **Info** | Plain-language description and output payload fields for downstream steps |
| **General** | Canvas label and read-only node ID |
| **AI** | Optional assistant to help draft settings from plain language |
| **Design** | Node-specific configuration fields |

### System (automatic — not edited by the user)

These fields are managed by the designer or runtime — you do not type into them directly:

| Property key | Label | Type | Required | Visible when | Notes |
|--------------|-------|------|----------|--------------|-------|
| `_nodeId` | Node ID | `node-id` | No | — | — |
| `_payloadFields` | Available Fields | `payload-panel` | No | — | — |

### User-configured — General tab

| Property key | Label | Type | Required | Visible when | Notes |
|--------------|-------|------|----------|--------------|-------|
| `label` | Label | `text` | No | — | Node label |

### User-configured — Design tab

| Property key | Label | Type | Required | Visible when | Notes |
|--------------|-------|------|----------|--------------|-------|
| `listPath` | List to filter | `iterator-list-path` | **Yes** | — | Path to a JSON array on the payload (e.g. node_12.rows or rows).

Drag a list field from “Available lists”, or type a dotted path. Each element is kept or removed based on your match rules. |
| `itemField` | Field on each item | `text` | No | — | name (e.g. SFTP files use name, not files.name) Dotted path on each list element to compare (e.g. name or path for SFTP/FTP file rows). If you picked files.name from Available Fields, use name — each item is already one file object. |
| `matchMode` | Match mode | `select` (`include` \| `exclude`; default: `include`) | No | — | Include keeps matching rows; exclude drops matching rows and keeps the rest. |
| `matchOperator` | Operator | `select` (`equals` \| `not_equals` \| `contains` \| `not_contains` \| `starts_with` \| `ends_with` \| `in` \| `not_in` \| `gt` \| `gte` \| `lt` \| `lte` \| `empty` \| `not_empty`; default: `equals`) | No | — | How to compare the item field to your match value. Use “Is in list” with comma- or newline-separated values. |
| `matchValue` | Match value | `payload-text` | No | `filterListShowMatchValue` | active or {{node_1.status}} Value to compare against. Supports {{placeholders}}. For “Is in list”, separate multiple values with commas or new lines. |
| `caseInsensitive` | Ignore uppercase/lowercase | `checkbox` (default: `true`) | No | — | When on, text comparisons treat A and a as the same. |
| `outputFieldKey` | Output field name | `text` (default: `filtered_items`) | No | — | filtered_items Name of the filtered array on the outgoing payload (default filtered_items). |

### CMS site configuration (not on this node's properties panel)

Credentials, API keys, mailers, SMTP, and integration defaults are configured in the CMS plugin under **Node Configuration**, not per step on this node. Link the flow to a domain before testing CMS-backed fields.

## Output payload fields

After this step runs, later nodes can reference these fields using placeholders such as
`{{filter_list.filtered_items}}`.

| Field key | Type | Description |
|-----------|------|-------------|
| `filtered_items` | array | Array of list elements that passed your filter rules (name matches output field key if customized). |
| `filtered_count` | number | Numeric value from this node's output. |
| `original_count` | number | Numeric value from this node's output. |
| `filter_list_error` | string | Text value from this node's output. |
| `filtered_items.0` | object | Nested field "filtered_items.0" from this node's output payload. |

## Validation rules

- **List to filter** (`listPath`) must be filled before the flow can be saved.

## Related nodes

Other steps in the same area of the palette:

- **Array to String** (`join-array-to-text`) — Logic
- **Check Condition** (`if`) — Logic
- **Logger** (`debug`) — Logic
- **Match Text** (`match-regex`) — Logic
- **Merge** (`merge`) — Logic