Read-SpectreSelection

Description

This function displays a selection prompt using Spectre Console. The user can select an option from the list of choices provided. The function returns the selected option.
With the -EnableSearch switch, the user can search for choices in the selection prompt by typing the characters instead of just typing up and down arrows.

If you require the option to have the user cancel the selection prompt without making a choice, you will need to add a “None of the above” or “Cancel” option to your choices and handle that in your code.
Alternatively you can instruct the user to use Ctrl+C to cancel the prompt, this will cancel the prompt and $null will be returned.

---

Examples

Example 1
This example demonstrates a selection prompt with a custom title and choices.

$color = Read-SpectreSelection -Message "Select your favorite color" -Choices @("Red", "Green", "Blue") -Color "Green"
# Type "↓", "↓", "↓", "↓", "↲" to wrap around the list and choose green
Write-SpectreHost "Your chosen color is '$color'"

Example 2
This example demonstrates a selection prompt with a custom title and choices, and search enabled.

$color = Read-SpectreSelection -Message "Select your favorite color" -Choices @("Blue", "Bluer", "Blue-est") -EnableSearch
# Type "b", "l", "u", "e", "r", "↲" to choose "Bluer"
Write-SpectreHost "Your chosen color is '$color'"

Example 3
This example demonstrates using pipeline input to provide choices to the selection prompt.

$selectedFile = @("file1.txt", "file2.txt", "file3.txt") | ForEach-Object { [PSCustomObject]@{ Name = $_ } } | Read-SpectreSelection -Message "Select a file to open" -ChoiceLabelProperty Name
# Type "↓", "↲" to select the second file
Write-SpectreHost "Selected file: $($selectedFile.Name)"

Example 4
This example demonstrates a selection prompt with a scriptblock to generate dynamic labels for complex objects.

$data = @(
    [PSCustomObject]@{ Name = "Alice"; Age = 30 },
    [PSCustomObject]@{ Name = "Bob"; Age = 25 },
    [PSCustomObject]@{ Name = "Charlie"; Age = 35 }
)
$selected = Read-SpectreSelection -Message "Select a person" -Choices $data -ChoiceLabelProperty { "$($_.Name) (Age: $($_.Age))" }
# Type "↓", "↲" to select Bob
Write-SpectreHost "Selected: $($selected.Name)"

---

Parameters

Message

The title of the selection prompt.

Type	Required	Position	PipelineInput	Aliases
[String]	false	named	false	Title Question Prompt

Choices

The list of choices to display in the selection prompt. ChoiceLabelProperty is required if the choices are complex objects rather than an array of strings.

Type	Required	Position	PipelineInput
[Array]	true	2	true (ByValue)

ChoiceLabelProperty

If the object is complex then the property of the choice object to use as the label in the selection prompt is required. This can be a string property name or a script block that takes the choice object as $_ and returns a string label.

Type	Required	Position	PipelineInput
[Object]	false	named	false

Color

The color of the selected option in the selection prompt.

Type	Required	Position	PipelineInput
[Color]	false	named	false

PageSize

The number of choices to display per page in the selection prompt.

Type	Required	Position	PipelineInput
[Int32]	false	named	false

EnableSearch

If this switch is present, the user can search for choices in the selection prompt by typing the characters instead of just typing up and down arrows.

Type	Required	Position	PipelineInput
[Switch]	false	named	false

TimeoutSeconds

Type	Required	Position	PipelineInput
[Int32]	false	named	false

SearchHighlightColor

The color of the search highlight in the selection prompt. Defaults to a slightly brighter version of the accent color.

Type	Required	Position	PipelineInput
[Color]	false	named	false

---

Syntax

Read-SpectreSelection [-Message <String>] [-Choices] <Array> [-ChoiceLabelProperty <Object>] [-Color <Color>] [-PageSize <Int32>] [-EnableSearch] [-TimeoutSeconds <Int32>] [-SearchHighlightColor <Color>] [<CommonParameters>]