ToggleSwitchWidget

A horizontal toggle switch that displays multiple options side-by-side and allows selection using arrow keys or mouse clicks.

ToggleSwitch is a focusable widget that presents a set of options in a compact horizontal layout. Users can navigate between options using left/right arrow keys or click directly on an option. It's commonly used for binary choices (On/Off) or selecting from a small set of mutually exclusive options (Low/Medium/High).

Basic Usage

Create a toggle switch using the fluent API by passing an array of options. Use OnSelectionChanged to respond when the user changes the selection:

csharp

dotnet run

State Management

ToggleSwitch selection state is managed internally by the node and preserved across re-renders. Use the OnSelectionChanged event to synchronize with your own application state when needed.

Multiple Options

ToggleSwitch isn't limited to binary choices—you can provide as many options as needed. Use the selectedIndex parameter to set the initial selection:

csharp

dotnet run

The widget automatically wraps around when navigating with arrow keys:

• Pressing Right on the last option moves to the first option
• Pressing Left on the first option moves to the last option

Selection Changed Event

Use OnSelectionChanged to respond when the user changes the selection:

csharp

dotnet run

The ToggleSelectionChangedEventArgs provides:

• SelectedIndex - The index of the newly selected option (0-based)
• SelectedOption - The text of the newly selected option
• Widget - The source ToggleSwitchWidget
• Node - The underlying ToggleSwitchNode
• Context - Access to the application context

Keyboard and Mouse Navigation

ToggleSwitch supports multiple input methods:

Input	Action
← Left Arrow	Select previous option (wraps to last)
→ Right Arrow	Select next option (wraps to first)
Mouse Click	Select the clicked option

Mouse Support

In terminals that support mouse input, users can click directly on any option to select it. The widget calculates which option was clicked based on the X position within the rendered text.

Focus Behavior

ToggleSwitch visually indicates its focus state with different bracket colors:

State	Appearance
Unfocused	Subtle gray brackets < Option >
Focused	Bright brackets with highlighted selection

csharp

When focused:

• The selected option has a bright background (white by default)
• The brackets change to a brighter color
• Arrow key navigation is active

When unfocused:

• The selected option still shows a subtle background (gray by default)
• The brackets are dimmed
• The selection is visible but less prominent

Focus Navigation

• Tab - Move focus to the next focusable widget
• Shift+Tab - Move focus to the previous focusable widget

Theming

Customize ToggleSwitch appearance using theme elements:

var theme = Hex1bTheme.Create()
    .Set(ToggleSwitchTheme.FocusedSelectedForegroundColor, Hex1bColor.Black)
    .Set(ToggleSwitchTheme.FocusedSelectedBackgroundColor, Hex1bColor.Cyan)
    .Set(ToggleSwitchTheme.UnfocusedSelectedForegroundColor, Hex1bColor.White)
    .Set(ToggleSwitchTheme.UnfocusedSelectedBackgroundColor, Hex1bColor.DarkGray)
    .Set(ToggleSwitchTheme.LeftBracket, "[ ")
    .Set(ToggleSwitchTheme.RightBracket, " ]");

await using var terminal = Hex1bTerminal.CreateBuilder()
    .WithHex1bApp((app, options) =>
    {
        options.Theme = theme;
        return ctx => /* ... */;
    })
    .Build();

await terminal.RunAsync();

Available Theme Elements

Element	Type	Default	Description
FocusedSelectedForegroundColor	Hex1bColor	Black	Text color of selected option when focused
FocusedSelectedBackgroundColor	Hex1bColor	White	Background of selected option when focused
UnfocusedSelectedForegroundColor	Hex1bColor	Black	Text color of selected option when unfocused
UnfocusedSelectedBackgroundColor	Hex1bColor	Gray	Background of selected option when unfocused
UnselectedForegroundColor	Hex1bColor	Default	Text color of unselected options
UnselectedBackgroundColor	Hex1bColor	Default	Background of unselected options
FocusedBracketForegroundColor	Hex1bColor	White	Bracket color when focused
FocusedBracketBackgroundColor	Hex1bColor	Default	Bracket background when focused
UnfocusedBracketForegroundColor	Hex1bColor	Gray	Bracket color when unfocused
UnfocusedBracketBackgroundColor	Hex1bColor	Default	Bracket background when unfocused
LeftBracket	string	"< "	Left bracket decoration
RightBracket	string	" >"	Right bracket decoration
Separator	string	" | "	Separator between options

Common Use Cases

Binary Toggles

Perfect for on/off, yes/no, enabled/disabled choices:

csharp

Mode Selection

Choose between a small set of modes:

csharp

Settings Panels

Multiple toggles in a form layout:

csharp

Related Widgets

• ButtonWidget - For triggering actions
• ListWidget - For selecting from larger sets of options
• TextWidget - For labels alongside toggle switches
• StackWidgets - For laying out multiple toggles