# List formatter

> Format the items of a collection and join them with spacers, or index into a list with a selector.

Format the items of a collection and join them with spacers, or index into a list with a selector.

The List formatter is both a formatter and a source. As a formatter it repeats a format for each item of any [IEnumerable](https://learn.microsoft.com/en-us/dotnet/api/system.collections.ienumerable), such as an array or a `List<T>`, joining the items with spacers. As a source it provides list-item selectors, so you can read an item by index or by the current iteration index. Apply the formatter explicitly with the name `list`, or omit the name to apply it implicitly to a collection.

{ /*  Mermaid source kept for the future doc platform; shown as the static image below until mermaid rendering is supported.  */ }

```mermaid
flowchart TD
    full["{value:list:template|spacer|final spacer}"]

    full --> p1["value"]
    full --> p2["list"]
    full --> p3["template"]
    full --> p4["spacer"]
    full --> p5["final spacer"]

    p1 --> d1["Any IEnumerable"]
    p2 --> d2["Formatter name: list<br/>(or implicit)"]
    p3 --> d3["Template: how each<br/>item is formatted"]
    p4 --> d4["Spacer: added after each<br/>item except the last"]
    p5 --> d5["Final spacer: replaces the<br/>last spacer (optional)"]

    classDef code   fill:#F5F5F5,stroke:#BDBDBD,color:#111;
    classDef orange fill:none,stroke:none,color:#F37021;
    classDef green  fill:none,stroke:none,color:#67BC6B;
    classDef purple fill:none,stroke:none,color:#765BA7;

    class full code;
    class p1,d1 orange;
    class p2,d2 green;
    class p3,d3 purple;
    class p4,d4 purple;
    class p5,d5 purple;

    linkStyle default stroke:#2196F3,stroke-width:1.5px;
```


**Anatomy of the list formatter syntax.:**
![](/api/media?file=/engine/6000.7/media/images/smart-strings-list-formatter.svg)

The format takes up to four parts, separated by the split character:

| Part        | Description                                                                         |
| ----------- | ----------------------------------------------------------------------------------- |
| Item format | The format applied to each item. An empty placeholder `{}` outputs the item itself. |
| Spacer      | Written between items.                                                              |
| Last spacer | Optional. Replaces the spacer before the final item.                                |
| Two spacer  | Optional. Used as the only spacer when the list has exactly two items.              |

The item format can contain nested placeholders, so each item can be formatted in detail, for example `{Sizes:list:{Width}x{Height}|, }`.

Spacers can include character literals, for example `\n` to put each item on its own line. A spacer that contains nested placeholders is formatted against the collection's parent value, not the individual item.

## Format a list

| Smart String              | Argument                  | Result              |
| ------------------------- | ------------------------- | ------------------- |
| `{0:list:{}\|, \|, and }` | `["one", "two", "three"]` | one, two, and three |
| `{0:list:{}\| and }`      | `["one", "two"]`          | one and two         |
| `{0:list:{:0.00}\|, }`    | `[1, 2, 3]`               | 1.00, 2.00, 3.00    |

## List-item selectors

As a source, the List formatter lets a selector index into an [IList](https://learn.microsoft.com/en-us/dotnet/api/system.collections.ilist). Use a numeric selector to read a specific item, and the `index` selector to read the current item's position while iterating.

A string is an `IEnumerable`, but the formatter does not treat strings or `IFormattable` values as lists.

| Smart String                    | Argument                | Result                    |
| ------------------------------- | ----------------------- | ------------------------- |
| `The value at index 1 is {0.1}` | `[1, 2, 3]`             | The value at index 1 is 2 |
| `{0.0} {0.1} {0.2}`             | `[1, "Hello", "World"]` | 1 Hello World             |

Use the `index` selector to synchronize two lists by iterating one and indexing the other at the same position:

| Smart String             | Argument                                             | Result                                |
| ------------------------ | ---------------------------------------------------- | ------------------------------------- |
| `{0:{} = {1.index}\|, }` | `[1, 2, 3, 4]` and `["one", "two", "three", "four"]` | 1 = one, 2 = two, 3 = three, 4 = four |

## Additional resources

* [Plural formatter](/engine/6000.7/manual/scripting/smart-strings/formatters/plural-formatter.md)
* [Dictionary source](/engine/6000.7/manual/scripting/smart-strings/sources/dictionary-source.md)
* [Smart Strings](/engine/6000.7/manual/scripting/smart-strings.md)