Controls Reference

SharpConsoleUI provides 39 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

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

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

Input Controls

Layout & Status Controls

Advanced Controls

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

Edit this page