Controls Reference

SharpConsoleUI provides 41 built-in UI controls for building rich console applications.

New to SharpConsoleUI? Start with the Tutorials — step-by-step guides that build real apps from scratch.

Table of Contents

• Overview
• Basic Input Controls
• Selection Controls
• Display Controls
• Drawing Controls
• Layout Controls
• Utility Controls
• Interfaces

Overview

All controls implement the IWindowControl interface and can be added to windows. Interactive controls implement additional interfaces like IInteractiveControl, IFocusableControl, and IMouseAwareControl.

Common Control Properties

All controls support:

• Name - Unique identifier for FindControl<T>(name) lookups
• Visible - Show/hide control
• Container - Reference to parent container
• Tag - Store custom data
• Layout properties (Width, Margin, Alignment, StickyPosition)
• Role / Outline - Available on controls implementing IRoleableControl. Apply a semantic Control Role (Primary, Success, Danger, …) so the control's colors come from the theme's palette instead of being set by hand. Role.Default (the default) leaves color resolution unchanged. Most controls implement IRoleableControl; a few non-themed ones (Canvas, Image, Video, Html, …) do not and have no Role/Outline.

Basic Input Controls

Controls for user input and interaction.

Control	Description	Details
ButtonControl	Clickable button with text	Click events, keyboard/mouse support
CheckboxControl	Toggle checkbox with label	Checked/unchecked state, change events
DatePickerControl	Locale-aware date picker	Segmented editing, calendar popup, min/max dates
PromptControl	Single-line text input	Enter key events, input validation, max length
TimePickerControl	Locale-aware time picker	12h/24h modes, seconds toggle, min/max times
MultilineEditControl	Multi-line text editor	Syntax highlighting (13 built-in languages via SyntaxHighlighters.For(...)), pluggable gutter, find/replace, undo/redo, word wrap
SliderControl	Value slider with thumb	Horizontal/vertical, step/large-step, keyboard/mouse drag
RangeSliderControl	Dual-thumb range slider	MinRange enforcement, tab to switch thumbs, range events
FormControl	Labeled-input form	Two-column grid (label | editor), typed field overloads (text/multiline/checkbox/dropdown/radio/slider), custom AddField, sections with collapse, row packing, validation, GetValues/Submit/Submitted, declarative XML loader

Selection Controls

Controls for selecting items from lists or hierarchies.

Control	Description	Details
ListControl	Scrollable list with selection	Single selection, item activation, keyboard navigation
TableControl	Interactive data grid	Virtual data, sorting, filtering (AND/OR), inline editing, multi-select, cell navigation, scrollbars
TreeControl	Hierarchical tree view	Expand/collapse nodes, selection, keyboard navigation
DropdownControl	Dropdown selection list	Click to expand, keyboard navigation, portal rendering
RadioControl	Single-select radio group	Typed RadioGroup<T> coordination, Required/AllowDeselect policies, label wrap, cross-layout grouping
MenuControl	Menu bar with dropdowns	Horizontal/vertical menus, submenus, separators, keyboard shortcuts

Display Controls

Controls for displaying formatted content.

Control	Description	Details
MarkupControl	Rich text with markup	Colors, bold, italic, clickable & keyboard-navigable links ([link=url]); renders Markdown (incl. links) via the [markdown] tag, optional border/header
HtmlControl	HTML content renderer	Parse & render HTML with images, links, tables, keyboard navigation
FigleControl	ASCII art text (Figlet)	Large stylized text, multiple fonts
ChatTranscriptControl	Agent/chat transcript	Role-tagged messages (User/Assistant/System/Tool/Error), token-by-token streaming, collapsible tool messages, thinking indicator, gradient headers, alpha bubbles
LogViewerControl	Log message viewer	Auto-scroll, filtering, severity colors
SpectreRenderableControl	Wrapper for Spectre widgets	Display Tables, Trees, Panels, Charts, etc.
PanelControl	Bordered container panel	Hosts child controls (a non-collapsible CollapsiblePanel); headers, border styles, padding, mouse. For bordered text, use MarkupControl with .WithBorder().
RuleControl	Horizontal rule/separator	Optional title, colors, horizontal line
SparklineControl	Time-series sparkline graph	Block, braille, or bidirectional modes; borders; titles
LineGraphControl	Multi-series line graph	Braille and ASCII rendering modes, gradients, Y-axis labels, live updates
BarGraphControl	Horizontal bar graph	Gradient color thresholds, labels, value display
SpinnerControl	Animated indeterminate-progress spinner	Preset styles + custom frames, per-frame markup, auto-animates via the animation manager. Also available as the inline [spinner] markup tag.

Drawing Controls

Controls for custom graphics and free-form drawing.

Control	Description	Details
CanvasControl	Free-form drawing surface	30+ drawing primitives, retained & immediate modes, thread-safe async painting
ImageControl	Image display with Kitty graphics	Full-resolution via Kitty/WezTerm/Ghostty with half-block fallback; PNG/JPEG/BMP/GIF/WebP/TIFF; async loading
VideoControl	Terminal video player	Kitty graphics + half-block/ASCII/braille fallbacks (auto-detected); FFmpeg decode; overlay bar; dynamic resize; looping

Layout Controls

Controls for organizing other controls.

Control	Description	Details
ColumnContainer	Vertical stack container	Stack controls vertically, padding, alignment
ScrollablePanelControl	Scrollable content area	Vertical scrolling, contains multiple controls
HorizontalGridControl	Multi-column layout	Variable-width columns, alignment, splitters
GridControl	WinUI-style 2D grid	Fixed/Auto/Star rows & columns, row/col spans, gaps, per-cell styling, any control per cell
FlowControl	Renders a flow inline in a region	Embeds Flow.Run/Flow.Wizard in a pane (vs. a modal); idle/done placeholder; normal focus scope
WizardControl	Runs a multi-step wizard inline	A FlowControl named/presetted for wizards (the discoverable door); wizard.Run(Flow.Wizard<T>()...); inline, not modal
SplitterControl	Resizable divider	Drag to resize adjacent columns
TabControl	Multi-page tab container	Tab headers, keyboard/mouse switching, state preservation
CollapsiblePanel	Click-to-expand container	Borderless/bordered header, markup title, custom icons, MaxContentHeight, IControlHost. Can also serve as a plain, non-collapsible panel hosting any control via .NonCollapsible() / .HideHeader()
NavigationView	Sidebar navigation + content area	WinUI-inspired nav pane, responsive display modes (Expanded/Compact/Minimal), content factories, gradient-transparent
ToolbarControl	Horizontal button toolbar	Auto-height, wrapping, separator lines, content padding, Tab navigation
StatusBarControl	Three-zone status bar	Left/center/right zones, clickable items, shortcut hints, above line separator
SeparatorControl	Visual separator	Simple horizontal line
PortalContentContainer	Portal overlay container	Host child controls in portal overlays, mouse/keyboard routing, focus tracking

Utility Controls

Special-purpose controls.

Control	Description	Details
TerminalControl	PTY-backed terminal emulator	Full xterm-256color, keyboard/mouse passthrough, auto-resize. Linux only.

Interfaces

Controls implement these interfaces based on their capabilities:

IWindowControl (Base Interface)

All controls implement this interface:

public interface IWindowControl : IDisposable
{
    IContainer? Container { get; set; }
    string? Name { get; set; }
    object? Tag { get; set; }
    bool Visible { get; set; }

    void PaintDOM(CharacterBuffer buffer, LayoutRect bounds, LayoutRect clipRect);
    Size MeasureDOM(int availableWidth);
    void Invalidate(Invalidation work);
}

IInteractiveControl

Controls that handle keyboard input:

public interface IInteractiveControl : IWindowControl
{
    bool IsEnabled { get; set; }
    bool ProcessKey(KeyEventArgs e);
}

Implemented by: Button, Checkbox, Prompt, MultilineEdit, List, Tree, Table, Dropdown, Menu, Canvas, Grid

IFocusableControl

Controls that can receive keyboard focus:

public interface IFocusableControl : IInteractiveControl
{
    bool HasFocus { get; }
    bool CanReceiveFocus { get; }
    event EventHandler? GotFocus;
    event EventHandler? LostFocus;
    void SetFocus();
}

Implemented by: Button, Checkbox, Prompt, MultilineEdit, List, Tree, Table, Dropdown, Canvas, Grid

IMouseAwareControl

Controls that handle mouse events:

public interface IMouseAwareControl : IWindowControl
{
    bool WantsMouseEvents { get; }
    bool CanFocusWithMouse { get; }
    event EventHandler<MouseEventArgs>? MouseClick;
    event EventHandler<MouseEventArgs>? MouseEnter;
    event EventHandler<MouseEventArgs>? MouseLeave;
    event EventHandler<MouseEventArgs>? MouseMove;
    void ProcessMouseEvent(MouseEventArgs e);
}

Implemented by: Button, List, Tree, Table, Dropdown, Menu, Toolbar, ScrollablePanel, Canvas, Grid

IContainer

The container surface used by child controls for rendering — colors, dirty tracking, and invalidation. It is not a child-mutation API; for that, see IControlHost below.

public interface IContainer
{
    Color BackgroundColor { get; set; }
    Color ForegroundColor { get; set; }
    ConsoleWindowSystem? GetConsoleWindowSystem { get; }
    void Invalidate(Invalidation work, IWindowControl? callerControl = null);
    int? GetVisibleHeightForControl(IWindowControl control);
}

Implemented by: ColumnContainer, ScrollablePanelControl, HorizontalGridControl, GridControl, NavigationView, Window, and other containers.

IControlHost

Capability interface for containers whose children are a flat list of IWindowControl. Lets you add, remove, clear, and enumerate children without binding to a concrete container type.

public interface IControlHost
{
    void AddControl(IWindowControl control);
    void RemoveControl(IWindowControl control);
    void ClearControls();
    IReadOnlyList<IWindowControl> Children { get; }
}

Implemented by: ScrollablePanelControl, ColumnContainer, CollapsiblePanel, GridControl, Window.

Not implemented by TabControl (tabs are title-keyed pages), MenuControl (children are MenuItem, not IWindowControl), ToolbarControl, or NavigationView — their child models are not a flat IWindowControl list, so forcing the contract would mean throwing NotSupportedException.

// Write once against the capability, reuse anywhere.
void PopulateForm(IControlHost host)
{
    host.AddControl(Controls.Label("Name:"));
    host.AddControl(Controls.Prompt().Build());
}

PopulateForm(scrollablePanel);
PopulateForm(column);
PopulateForm(window);

ColumnContainer and Window keep their existing native names (AddContent/Contents on ColumnContainer; RemoveContent/GetControls() on Window); the IControlHost members are implemented via explicit interface forwarding so the public APIs are unchanged.

Quick Reference

Creating Controls

// Using builders (recommended)
var button = Controls.Button("Click Me")
    .WithWidth(20)
    .OnClick((s, e, w) => { })
    .Build();

// Using constructors
var button = new ButtonControl
{
    Text = "Click Me",
    Width = 20
};
button.OnClick += (s, e) => { };

// Using static helpers
var label = Controls.Label("Simple text");
var header = Controls.Header("Title");

// Canvas control
var canvas = new CanvasControl(80, 24);

Adding to Windows

window.AddControl(control);

Finding Controls by Name

// Name a control
window.AddControl(
    Controls.Prompt("Name:")
        .WithName("nameInput")
        .Build()
);

// Find it later
var input = window.FindControl<PromptControl>("nameInput");
if (input != null)
{
    string text = input.Text;
}

Common Patterns

Input Form

window.AddControl(Controls.Header("Contact Form"));
window.AddControl(Controls.Prompt("Name:").WithName("name").Build());
window.AddControl(Controls.Prompt("Email:").WithName("email").Build());
window.AddControl(Controls.Button("Submit")
    .OnClick((s, e, w) =>
    {
        var name = w.FindControl<PromptControl>("name")?.Text;
        var email = w.FindControl<PromptControl>("email")?.Text;
        // Process form...
    })
    .Build());

Data Display

var list = Controls.List()
    .AddItem("Item 1")
    .AddItem("Item 2")
    .AddItem("Item 3")
    .OnItemActivated((s, item, w) =>
    {
        windowSystem.NotificationStateService.ShowNotification(
            "Selected", item.Text, NotificationSeverity.Info);
    })
    .Build();

window.AddControl(list);

Layout

var grid = Controls.HorizontalGrid()
    .WithAlignment(HorizontalAlignment.Stretch)
    .Column(col => col.Add(Controls.Label("Left")))
    .Column(col => col.Add(Controls.Label("Center")))
    .Column(col => col.Add(Controls.Label("Right")))
    .Build();

window.AddControl(grid);

Next Steps

Browse detailed documentation for specific controls:

Essential Controls

• ButtonControl - Interactive buttons
• PromptControl - Text input
• ListControl - Item lists
• MarkupControl - Formatted text

Input Controls

• DatePickerControl - Date picker with calendar popup
• TimePickerControl - Time picker with 12h/24h modes

Layout & Status Controls

• ToolbarControl - Horizontal button toolbar with wrapping
• StatusBarControl - Three-zone status bar with clickable items

Advanced Controls

• TableControl - Interactive data grid with virtual data
• TabControl - Multi-page tab container
• CollapsiblePanel - Click-to-expand container for progressive disclosure
• NavigationView - Sidebar navigation with content area
• CanvasControl - Free-form drawing surface
• TerminalControl - Embedded PTY terminal (Linux)

Cross-Cutting Features

• Syntax Highlighting - 13 built-in highlighters + registry, used by MultilineEditControl and Markdown code blocks
• Markup Syntax - Colors, decorations, spinners, and the [markdown] tag

---

Back to Main Documentation