# Selector

> Pick one item or a subset from a list by position, range, random sample, rule or name. Selector sends the pick and the rest to two outputs, for free.

Source: https://nodaro.ai/docs/nodes/automate/selector

The **Selector** node picks one item, or several items, from a list. You choose how to pick: by position, by range, at random, by a rule on a field, or by name. Selector sends the picked items to its **Picked** output and every other item to its **Rest** output. It runs instantly, makes no model call and costs no credits.

- Found in: Automate › Lists & Batching
- Output: text
- API type: `selector`

## When to use it
- The same pick feeds several nodes. One Selector replaces the same setting on several connections.
- You want a random item from a list, and you want to repeat the same pick later with a seed.
- You want the item whose field has a given value, such as the character named `hero`, or every item with a score of 15 or more.
- You want to send the items you did not pick somewhere else, through **Rest**.
- You want to cycle through a short list with a number from another node.

## Quick start
### Add the node

Press Tab on the canvas and choose **Automate › Lists & Batching › Selector**.

### Connect a list

Wire a list into the **List** input, for example from a [List](https://nodaro.ai/docs/nodes/automate/list), [Split Text](https://nodaro.ai/docs/nodes/automate/split-text), [Filter List](https://nodaro.ai/docs/nodes/automate/filter-list) or an [Extract Field](https://nodaro.ai/docs/nodes/automate/extract-field) node with its output set to a list.

### Choose a mode

Open the settings panel, choose a **Mode**, and complete its fields. The modes are described below.

### Connect the outputs and run

Connect **Picked** to the next node, and **Rest** to another branch if you need the other items. After a run, the panel shows the counts under **Last run**, such as "2 picked · 3 rest".

Workflow: Selector draws three random prompts from a list of ten, and Generate Image runs once for each prompt it picked.

- List → Selector (list)
- Selector → Generate Image (picked · Each)

## Inputs and outputs
| Input or output | Accepts or sends | What it does |
| --- | --- | --- |
| **List** | Lists of text, images, videos, audio or JSON items | The list to pick from. When several nodes are connected, their lists are joined in the order you connected them. |
| **Picked** | A list | The items the mode picked. A mode that picks one item sends a list with one item. |
| **Rest** | A list | Every item that was not picked, in the original order. |

Together, **Picked** and **Rest** always cover every input item, and no item is in both. Selector splits by position, not by value, so duplicates land on the correct side. For example, with `a, b, a, c` and a range from 2 to 3, **Picked** is `b, a` and **Rest** is `a, c`.

## Modes

| Mode | Fields | Picks | Example |
| --- | --- | --- | --- |
| **Item (single index)** | **Index** | 1 item | On `a, b, c, d`, the index `last-1` picks `c`. |
| **Range (from/to/step)** | **From**, **To**, **Step** | Several items | On `a, b, c, d, e`, from `2` to `4` picks `b, c, d`. |
| **List (comma expression)** | **Expression** | Several items | On `a, b, c, d, e`, the expression `1, 3, 5` picks `a, c, e`. |
| **Random (seeded)** | **Seed (optional)**, **Count** | **Count** items | On `a, b, c, d`, a seed of `42` and a count of 2 always picks the same two items. |
| **Modulo (cycle by index)** | **Divisor** | 1 item | On `a, b, c`, a divisor of `5` picks `c`. |
| **Predicate (filter)** | **Field**, **Operator**, **Value**, **Match**, **Case-sensitive** | 1 item or all matches | On items with a `score` field, `score` greater or equal `15` with **Match** set to **All** picks every item scoring 15 or more. |
| **Named key (look up)** | **Field**, **Value** | 0 or 1 item | On characters with a `name` field, `name` = `hero` picks the hero. |

### Item

**Index** counts from 1. Write a number such as `3`, or count from the end with `last` and `last-1`, `last-2`, and so on. An index past the end of the list uses the nearest valid item. An index that cannot be read uses the first item, and the node shows the warning "Invalid index expression — used first item".

### Range

**From** and **To** are both included and count from 1. A negative **Step** walks backwards: from `last` to `1` with step `-1` reverses the whole list. A step of `0` counts as `1`. A range that runs forward with a negative step, or backward with a positive step, picks nothing.

### List

**Expression** mixes single positions and ranges, separated by commas, for example `1, 3..5, last`. Positions are kept in the order you write them, and a position written twice is picked twice. Other examples: `1..5`, `1..10:2` for every second item, and `1..last-1` for all items except the last. A part that cannot be read makes the node pick every item.

### Random

**Count** is the number of items to draw, and defaults to 1. Each item is drawn at most once, and a count larger than the list picks the whole list. With a **Seed**, the same seed and the same list always give the same pick. Without a seed, every run draws again.

### Modulo

Modulo picks one item by dividing the **Divisor** by the length of the list. The remainder is the position, counted from 0. For example, a divisor of `5` on a list of 3 items leaves a remainder of 2, which is the third item. Use it to cycle through a short list with a changing number from another node. A divisor that is not a number uses the first item and shows a warning.

### Predicate

Predicate keeps items whose **Field** passes a test. Leave **Field** empty to test the whole item. The **Operator** is one of **equals**, **not equals**, **greater than**, **less than**, **greater or equal**, **less or equal**, **contains**, **does not contain**, **starts with**, **ends with**, **matches regex**, **exists** and **does not exist**. With **Match** set to **First**, Selector picks only the first match; with **All**, it picks every match. A rule that matches nothing sends every item to **Rest**.

### Named key

Named key is the short form of Predicate for a lookup by name: it picks the first item whose **Field** equals the **Value**. When nothing matches, **Picked** is empty and every item goes to **Rest**.

## Use a value from another node

Four fields accept the label of another node in curly braces, such as `{CharacterName}`. When the Selector runs, the braces are replaced with that node's value.

| Field | Mode | Typical use |
| --- | --- | --- |
| **Divisor** | Modulo | Cycle through a list with a number from another node. |
| **Value** | Predicate | Compare each item with another node's output. |
| **Value** | Named key | Look up the item named by another node, such as `{CharacterName}`. |
| **Seed** | Random | Make the random pick depend on another node, such as `{Project}`. |

Every other field is read exactly as typed. Read more in [Prompt variables](https://nodaro.ai/docs/concepts/prompt-variables).

## When a setting is wrong

Selector never stops a workflow because of a setting. Each problem has a safe result:

| Case | Result |
| --- | --- |
| No list connected, or an empty list | **Picked** and **Rest** are both empty. The node completes without an error. |
| An index that cannot be read | The first item, with a warning on the node. |
| An index past the end | The nearest valid item. |
| A divisor that is not a number | The first item, with a warning on the node. |
| A count larger than the list | The whole list. |
| A Predicate or Named key that matches nothing | **Picked** is empty, and **Rest** has every item. |

The node fails only on an unexpected error, and then shows the error message.

## Selector or a connection setting

Every connection can also pick items with its **Item** mode, or with the range and list tabs of **Each** and **Bundle**. The two use the same position rules.

| Use a connection setting when | Use the Selector node when |
| --- | --- |
| One next node needs a simple pick by position, range or list | The same pick feeds several next nodes |
| You want the pick hidden on the canvas | The pick matters enough to show as a labeled node |
| Item, range or list is all you need | You need Random, Modulo, Predicate or Named key |
| One output is enough | You want the other items on **Rest** |

Read [Lists and batching](https://nodaro.ai/docs/concepts/lists-and-batching) for every connection mode.

## Credits
Selector is free in every edition.

## Tips
- **Run the next node per pick.** **Picked** always sends a list. Set the connection from **Picked** to **Each** to run the next node once per picked item.
- **Check the counts.** **Last run** shows how many items went to **Picked** and to **Rest**, which is the quickest way to test a rule.
- **Filter many, pick one.** To keep every item that matches several conditions, use [Filter List](https://nodaro.ai/docs/nodes/automate/filter-list). To pick one item or a slice, use Selector.

## Frequently asked questions

### What is the difference between the Selector node and the Item mode on a connection?

A connection's Item, range and list picks are quick choices for one next node and stay invisible on the canvas. The Selector node shows the pick as a labeled node and can feed several nodes. It also sends the unpicked items to a Rest output, and adds the Random, Modulo, Predicate and Named key modes.

### Can a random pick be repeated exactly?

Yes. Enter a Seed, and the same seed with the same list always gives the same pick. Leave Seed empty to get a new random pick on every run.

### What happens when a Selector setting is wrong?

The workflow keeps running. An invalid index uses the first item and shows a warning. An index past the end uses the nearest item, and a rule that matches nothing sends every item to Rest.

### Does the Selector node cost credits?

No. Selector is free in every edition. It runs instantly and never calls a model.

### How do I run the next node once for every picked item?

Set the connection from the Picked output to Each. The next node then runs once per picked item.