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.

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)"

--:----:--

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.

Type	Required	Position	PipelineInput
`[String]`	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 <String>] [-Color <Color>] [-PageSize <Int32>] [-EnableSearch] [-TimeoutSeconds <Int32>] [-SearchHighlightColor <Color>] [<CommonParameters>]