> ## Documentation Index
> Fetch the complete documentation index at: https://luau.limerence.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# List

> A vertical list the user can pick from, with search, filters, and rename.

Also has everything from [ElementHandle](/ui/classes/element-handle).

A vertical list. `items` are strings, or tables like `{ id, name?, icon? }`. Value is the id of the selected item.

|                |                                                   |
| -------------- | ------------------------------------------------- |
| **Value type** | `string?` (selected `id`)                         |
| **Items**      | `string` or [ListItem](/reference/types#listitem) |
| **Created by** | [Section:AddList](/ui/classes/section#addlist)    |

## Creation

```luau theme={null}
section:AddList(key, label, items?, default?)
```

***

## SetItems

```luau theme={null}
list:SetItems(items: { string | ListItem }): ()
```

Replace all items.

***

## AddItem

```luau theme={null}
list:AddItem(item: string | ListItem): ()
```

***

## RemoveItem

```luau theme={null}
list:RemoveItem(id: string): ()
```

***

## SetSelected

```luau theme={null}
list:SetSelected(id: string?): ()
```

Pass `nil` to clear.

***

## GetSelected / GetSelectedItem

```luau theme={null}
list:GetSelected(): string?
list:GetSelectedItem(): ListItem?
```

`GetSelectedItem` returns the full item table.

***

## SetShowSearch

```luau theme={null}
list:SetShowSearch(show: boolean): ()
```

Toggle the search field.

***

## SetMaxHeight

```luau theme={null}
list:SetMaxHeight(pixels: number): ()
```

Cap the scroll height.

***

## SetEmptyText

```luau theme={null}
list:SetEmptyText(text: string): ()
```

Shown when there are no items.

***

## SetPlaceholder

```luau theme={null}
list:SetPlaceholder(text: string): ()
```

Search field placeholder.

***

## AddFilter

```luau theme={null}
list:AddFilter(name: string, comparator: ((item: ListItem) -> boolean)?): ()
```

Filter which items the user sees. Without a `comparator`, the built-in default is used.

***

## RemoveFilter

```luau theme={null}
list:RemoveFilter(name: string): ()
```

***

## SetFilter

```luau theme={null}
list:SetFilter(name: string?): ()
```

Activate a filter by name. Pass `nil` to clear.

***

## GetFilter

```luau theme={null}
list:GetFilter(): string?
```

***

## SetRenamable / IsRenamable

```luau theme={null}
list:SetRenamable(renamable: boolean): ()
list:IsRenamable(): boolean
```

Let the user rename items in place.

***

## OnRename

```luau theme={null}
list:OnRename(callback: (id: string, newName: string) -> ()): () -> ()
```

Runs when the user commits a rename.

***

## BeginEdit / CancelEdit / CommitEdit

```luau theme={null}
list:BeginEdit(id: string): ()
list:CancelEdit(): ()
list:CommitEdit(newName: string): ()
```

Control inline renaming from code.