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

# Selections

> Build single-select or multi-select pickers with persistent values and startup execution.

`AddSelection()` creates a row with a flyout. A selection uses one of two picker modes:

| Mode | Configuration | Stored value | Main callback |
| :- | :- | :- | :- |
| Single-select | `SingleSelect = true` or omitted | One value or `nil` | `Callback(value)` |
| Multi-select | `MultiSelect = true` | Array of values | `Callback(values)` |

**Single-select is the default.** You can omit `SingleSelect` entirely, or set `SingleSelect = true` explicitly. Set `MultiSelect = true` to opt into multi-select behavior. Enabling both `SingleSelect` and `MultiSelect` raises an error.

## Single-select picker

```lua theme={null}
local target = tab:AddSelection({
	Info = {
		Title = "Target",
		Description = "Choose which target to use.",
	},
	SingleSelect = true,
	DefaultValue = "Nearest",
	InternalInfo = {
		UniqueCommandId = "target",
		Aliases = { "dest" },
	},
	Callback = function(value)
		print("Selected:", value)
	end,
})

target:AddOption({ Info = { Title = "Nearest" }, Value = "Nearest" })
target:AddOption({ Info = { Title = "Self" }, Value = "Self" })
target:AddOption({ Info = { Title = "Last Target" }, Value = "LastTarget" })
```

`SingleSelect` can be supplied as either:

```lua theme={null}
SingleSelect = true
```

or:

```lua theme={null}
InternalInfo = { SingleSelect = true }
```

The selected option is the option's `Value`. Turning the selected option off clears the stored value.

## Multi-select picker

```lua theme={null}
local features = tab:AddSelection({
	Info = {
		Title = "Features",
		Description = "Choose every feature to enable.",
	},
	MultiSelect = true,
	DefaultValue = { "ESP", "Tracers" },
	InternalInfo = {
		UniqueCommandId = "features",
	},
	Callback = function(values)
		for _, value in ipairs(values) do
			print("Selected:", value)
		end
	end,
})

features:AddOption({ Info = { Title = "ESP" }, Value = "ESP" })
features:AddOption({ Info = { Title = "Tracers" }, Value = "Tracers" })
features:AddOption({ Info = { Title = "Chams" }, Value = "Chams" })
```

`MultiSelect` can also be supplied through `InternalInfo.MultiSelect`.

The stored value is always an array. Selecting an option adds its `Value` to the array; turning it off removes that value. The order is the order in which values were selected.

For multi-select option callbacks, the signature is:

```lua theme={null}
Callback = function(optionEnabled, selectedValues)
	print("Option state:", optionEnabled)
	print("Selected count:", #selectedValues)
end
```

## Selection modes

Single-select is the default mode. These configurations are equivalent:

```lua theme={null}
-- Default: single-select
local target = tab:AddSelection({
	Info = { Title = "Target" },
})
```

```lua theme={null}
-- Explicit single-select
local target = tab:AddSelection({
	Info = { Title = "Target" },
	SingleSelect = true,
})
```

Use `MultiSelect = true` when multiple options may be selected at once:

```lua theme={null}
local features = tab:AddSelection({
	Info = { Title = "Features" },
	MultiSelect = true,
})
```

`SingleSelect` and `MultiSelect` are mutually exclusive. Do not enable both. `InternalInfo.SingleSelect` and `InternalInfo.MultiSelect` are aliases for the corresponding public flags.

`AddButton()` acts like an option in both picker modes. Other flyout components such as text boxes, sliders, and labels can still be added when needed.

The parent selection title and description tooltip support Roblox rich-text markup by
default:

```lua theme={null}
tab:AddSelection({
	Info = {
		Title = "<b>Target</b> <font color=\"#9D7BFF\">Player</font>",
		Description = "<i>Choose an active target.</i>",
	},
})
```

Set `RichText = false` on the selection config or inside `Info` to opt out. This
setting applies to the parent row; nested options use their own component settings.

## Option callbacks

An option can supply its own callback in either picker mode:

```lua theme={null}
target:AddOption({
	Info = { Title = "Nearest" },
	Value = "Nearest",
	Callback = function(optionEnabled, selectionValue)
		print(optionEnabled, selectionValue)
	end,
})
```

For single-select, `selectionValue` is the selected value or `nil`.

For multi-select, `selectionValue` is an array containing all selected values at that moment.

## Configuration

**Info.Title** `string` (default: "Selection")

Text shown on the parent row.

**Info.Description** `string`

Tooltip text shown instantly while hovering the row. Use `\n` for line breaks.

**RichText** `boolean` (default: true)

Enables rich-text markup for the selection title and description tooltip. Set to
`false` to opt out. `Info.RichText` is also accepted.

**SingleSelect** `boolean`

Enables single-select picker semantics. This is the default when `MultiSelect` is not enabled. Do not enable `MultiSelect` at the same time.

**MultiSelect** `boolean` (default: false)

Enables multi-select picker semantics. When `true`, this overrides the default single-select mode. The selection value is stored as an array. Do not enable `SingleSelect` at the same time.

**DefaultValue** `any`

Initial value used when no saved value exists. Use a single value for `SingleSelect` and an array of values for `MultiSelect`.

**Save** `boolean` (default: false)

Persists the current selection value under `Settings[InternalInfo.UniqueCommandId]`. For multi-select selections, the saved value is an array. The saved value is restored on the next initialization.

**InternalInfo.SingleSelect** `boolean`

Alias for `SingleSelect`.

**InternalInfo.MultiSelect** `boolean`

Alias for `MultiSelect`.

**InternalInfo.UniqueCommandId** `string`

Stable command ID. A random ID is generated when omitted. Provide a stable ID when using `Save` or startup persistence so saved data can be restored across runs.

**InternalInfo.Bindable** `boolean` (default: false)

Adds a right-click menu for assigning or removing a keybind. The bound callback invokes the current selection callback path.

**InternalInfo.StartupAvailable** `boolean` (default: false)

Adds a persisted **Toggle Startup** action to the context menu. In picker modes, enabling it runs the main selection callback during initialization using the restored value. Single-select passes one value; multi-select passes the restored array.

**InternalInfo.Save** `boolean`

Alias for `Save`.

**Aliases** `string[]`

Alternate Quick Commands names. `Info.Aliases` and `InternalInfo.Aliases` are also recognized.

**Callback** `function`

Clicking the parent row calls the main selection callback. Single-select passes the current value. Multi-select passes an array of selected values. Quick Commands also pass the selected value or selected array first, followed by any remaining arguments.

## Saved selection + startup

Use `Save = true` with `InternalInfo.UniqueCommandId` and `StartupAvailable = true` to persist the picker value and optionally run it during startup.

### Single-select startup

```lua theme={null}
local target = tab:AddSelection({
	Info = { Title = "Target" },
	SingleSelect = true,
	DefaultValue = "Nearest",
	Save = true,
	InternalInfo = {
		UniqueCommandId = "target",
		StartupAvailable = true,
	},
	Callback = function(value)
		print("Selected at startup:", value)
	end,
})

target:AddOption({ Info = { Title = "Nearest" }, Value = "Nearest" })
target:AddOption({ Info = { Title = "Self" }, Value = "Self" })
```

### Multi-select startup

```lua theme={null}
local features = tab:AddSelection({
	Info = { Title = "Features" },
	MultiSelect = true,
	DefaultValue = { "ESP", "Tracers" },
	Save = true,
	InternalInfo = {
		UniqueCommandId = "features",
		StartupAvailable = true,
	},
	Callback = function(values)
		print("Restored selections:", table.concat(values, ", "))
	end,
})

features:AddOption({ Info = { Title = "ESP" }, Value = "ESP" })
features:AddOption({ Info = { Title = "Tracers" }, Value = "Tracers" })
features:AddOption({ Info = { Title = "Chams" }, Value = "Chams" })
```

When **Toggle Startup** is enabled, the startup preference is stored as `Startup[commandId] = true`. The picker value is stored separately under `Settings[commandId]`.

For example, a multi-select configuration can contain:

```lua theme={null}
Startup["features"] = true
Settings["features"] = {
	"ESP",
	"Tracers",
}
```

On the next library initialization, the saved array is restored before the startup callback runs.

## Quick Commands

A selection command can match an option by `Value` or display title. The matcher checks exact, prefix, and substring matches, trying longer multi-word matches before shorter ones.

For single-select selections, the first matched option is selected and any remaining arguments are forwarded to the callback.

For multi-select selections, multiple options can be supplied as separate arguments or as a comma-separated list. The supplied options replace the current selected-value array for that command invocation, and any remaining arguments are forwarded afterward.

```text theme={null}
dest Nearest
dest Last Target
features ESP
features ESP Tracers
features ESP,Tracers
features ESP,Tracers true
```

For a multi-select command with no option match, the existing selection is preserved and all arguments are forwarded to the callback. This makes commands such as `hide true` useful for applying an additional argument to the current selection.

## Selection handle

```lua theme={null}
local target = tab:AddSelection({
	Info = { Title = "Target" },
	SingleSelect = true,
	DefaultValue = "Nearest",
})

target:AddOption({ Info = { Title = "Nearest" }, Value = "Nearest" })
target:AddOption({ Info = { Title = "Self" }, Value = "Self" })

print(target:GetValue())
target:SetValue("Self")
target:UpdateSummary("Current target")
```

For multi-select:

```lua theme={null}
local features = tab:AddSelection({
	Info = { Title = "Features" },
	MultiSelect = true,
	DefaultValue = { "ESP" },
})

features:AddOption({ Info = { Title = "ESP" }, Value = "ESP" })
features:AddOption({ Info = { Title = "Tracers" }, Value = "Tracers" })

local selected = features:GetValue()
features:SetValue({ "ESP", "Tracers" })
```

| Method | Behavior |
| :- | :- |
| `getValue()` / `GetValue()` | Returns the stored value. In multi-select mode, returns an array of selected values. |
| `SetValue(value)` | Stores a value and updates the selected visuals. In multi-select mode, pass an array of values. |
| `UpdateSummary(text)` | Replaces the displayed summary with `<title> - <text>`. |
| `AddButton(config)` | Adds a child button that behaves as an option in single- and multi-select modes, and returns the selection handle for chaining. |
| `AddOption(config)` | Adds a picker option. The option's `Value` identifies the stored selection. |
| `AddTextBox(config)` | Adds a nested text input and returns the selection handle. |
| `AddSlider(config)` | Adds a nested slider and returns the selection handle. |
| `AddLabel(config)` | Adds a nested label and returns the selection handle. |

> [!NOTE]
>
> For picker options, the library reads the option's `Value`, display title, callback, and an optional `InternalInfo.UniqueCommandId`. Other component flags are not propagated from the option config.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.