SpectreRenderableControl

Wrap any Spectre.Console IRenderable for display within the SharpConsoleUI window system.

Overview

SpectreRenderableControl is a bridge control that hosts any Spectre.Console renderable — tables, panels, bar charts, trees, rules, calendars, breakdown charts, or any custom IRenderable — inside a SharpConsoleUI window. The renderable is rendered to ANSI, parsed back into the framework's cell buffer, and painted with full color, alignment, and margin support.

This is the only place in the framework that renders Spectre.Console IRenderable objects. The control captures the renderable's ANSI output, parses the escape sequences (SGR colors including 16-color, 256-color, and 24-bit RGB) into native cells, and handles Unicode width correctly (wide characters, combining marks, and VS16 emoji widening). All other controls use the built-in markup parser instead.

Spectre.Console is an optional dependency. SharpConsoleUI references Spectre.Console (0.49.1) only for this control. If your application does not host Spectre renderables, you do not need to use it — but the package is already pulled in transitively by the library, so SpectreRenderableControl is always available.

See also: MarkupControl

Quick Start

using SharpConsoleUI.Controls;
using Spectre.Console;

var table = new Table()
    .AddColumn("Name")
    .AddColumn("Role");
table.AddRow("Alice", "Engineer");
table.AddRow("Bob", "Designer");

var control = SpectreRenderableControl.Create()
    .WithRenderable(table)
    .WithMargin(1)
    .Build();

window.AddControl(control);

Builder API

Create a builder via SpectreRenderableControl.Create().

Content

.WithRenderable(IRenderable renderable)   // The Spectre.Console renderable to display

Alignment

.WithAlignment(HorizontalAlignment alignment)       // Left (default), Center, Right
.WithVerticalAlignment(VerticalAlignment alignment) // Top (default), Middle, Bottom
.Centered()                                         // Shortcut for HorizontalAlignment.Center

Layout

.WithMargin(int left, int top, int right, int bottom)
.WithMargin(int margin)            // Uniform margin on all sides
.WithMargin(Margin margin)
.WithWidth(int width)              // Fixed render width
.Visible(bool visible = true)
.Hidden()
.StickyTop()
.StickyBottom()
.WithStickyPosition(StickyPosition position)

Colors

.WithBackgroundColor(Color color)
.WithForegroundColor(Color color)
.WithColors(Color foreground, Color background)

Identity

.WithName(string name)   // For FindControl queries
.WithTag(object tag)     // Custom data storage

Mouse

.WithMouseEvents(bool wants = true)     // Enable/disable mouse events (default enabled)
.CanFocusWithMouse(bool canFocus = true) // Allow mouse to focus the control (default false)
.OnClick(EventHandler<MouseEventArgs> handler)
.OnDoubleClick(EventHandler<MouseEventArgs> handler)
.OnMouseEnter(EventHandler<MouseEventArgs> handler)
.OnMouseLeave(EventHandler<MouseEventArgs> handler)
.OnMouseMove(EventHandler<MouseEventArgs> handler)

Properties

Property Type Default Description
Renderable IRenderable? null The Spectre.Console renderable to display
BackgroundColor Color Container/theme fallback Background color for rendering; falls back to container or theme colors if not explicitly set
ForegroundColor Color Theme WindowForegroundColor, else White Foreground color for rendering; falls back to theme colors if not explicitly set
WantsMouseEvents bool true Whether the control receives mouse events
CanFocusWithMouse bool false Whether the control can receive focus via mouse clicks
HorizontalAlignment HorizontalAlignment Left Horizontal alignment of the rendered content within its bounds
VerticalAlignment VerticalAlignment Top Vertical alignment of the control
Margin Margin 0,0,0,0 Outer margin around the content
Width int? null Fixed render width; uses available width when null
Visible bool true Whether the control is rendered
StickyPosition StickyPosition None Pins the control to the top or bottom of the window
Name string? null Identifier for FindControl queries
Tag object? null Arbitrary user data

Events

Event Arguments Description
MouseClick MouseEventArgs Raised on a single left-button click
MouseDoubleClick MouseEventArgs Raised on a left-button double-click (driver-provided or detected via threshold)
MouseRightClick MouseEventArgs Raised on a right-button (Button3) click
MouseEnter MouseEventArgs Raised when the mouse pointer enters the control
MouseLeave MouseEventArgs Raised when the mouse pointer leaves the control
MouseMove MouseEventArgs Raised when the mouse moves within the control

Mouse Support

SpectreRenderableControl implements IMouseAwareControl.

Interaction Behavior
Left click Raises MouseClick; consumes the event
Left double-click Raises MouseDoubleClick; consumes the event
Right click Raises MouseRightClick; consumes the event
Mouse wheel (any direction) Not consumed — bubbles up to the parent so scrollable containers can handle it
Pointer enter/leave Raises MouseEnter / MouseLeave and invalidates the container
Pointer move Raises MouseMove

Mouse handling is skipped entirely when WantsMouseEvents is false.

Methods

Method Description
SetRenderable(IRenderable renderable) Replaces the displayed renderable and invalidates the container for a repaint
static Create() Returns a new SpectreRenderableBuilder

Examples

Table

using Spectre.Console;

var table = new Table()
    .Border(TableBorder.Rounded)
    .AddColumn("[bold]Service[/]")
    .AddColumn("[bold]Status[/]");
table.AddRow("Web", "[green]Online[/]");
table.AddRow("Database", "[green]Online[/]");
table.AddRow("Cache", "[red]Offline[/]");

window.AddControl(
    SpectreRenderableControl.Create()
        .WithRenderable(table)
        .WithMargin(1)
        .Build()
);

Panel with a Title

using Spectre.Console;

var panel = new Panel("Deployment completed successfully.")
{
    Header = new PanelHeader("[bold green]Result[/]"),
    Border = BoxBorder.Double
};

window.AddControl(
    SpectreRenderableControl.Create()
        .WithRenderable(panel)
        .Centered()
        .Build()
);

Bar Chart

using Spectre.Console;

var chart = new BarChart()
    .Width(60)
    .Label("[bold]CPU Usage by Core[/]")
    .AddItem("Core 0", 72, Color.Green)
    .AddItem("Core 1", 45, Color.Yellow)
    .AddItem("Core 2", 91, Color.Red)
    .AddItem("Core 3", 30, Color.Green);

window.AddControl(
    SpectreRenderableControl.Create()
        .WithRenderable(chart)
        .WithMargin(1)
        .Build()
);

Updating the Renderable Live

var control = SpectreRenderableControl.Create()
    .WithName("liveChart")
    .Build();

window.AddControl(control);

// Later, from the UI thread, swap in a new renderable
var spectre = window.FindControl<SpectreRenderableControl>("liveChart");
if (spectre != null)
{
    var updated = new BreakdownChart()
        .AddItem("Used", 60, Color.Red)
        .AddItem("Free", 40, Color.Green);

    spectre.SetRenderable(updated);
}

When updating from a background thread (timer, Task.Run), marshal the call:

windowSystem.EnqueueOnUIThread(() => spectre.SetRenderable(updated));

Constructor Usage

using Spectre.Console;

var rule = new Rule("[yellow]Section[/]")
{
    Justification = Justify.Left
};

// Direct construction is also supported
var control = new SpectreRenderableControl(rule);
window.AddControl(control);

Mouse Interaction

var control = SpectreRenderableControl.Create()
    .WithRenderable(new Panel("Click me"))
    .WithMouseEvents()
    .OnClick((s, e) => logService.LogInfo("Renderable clicked"))
    .OnMouseEnter((s, e) => logService.LogInfo("Mouse entered"))
    .Build();

window.AddControl(control);

Best Practices

  1. Build the renderable with Spectre's own API: Configure tables, charts, and panels using Spectre.Console builders, then hand the finished IRenderable to WithRenderable().
  2. Set a width for predictable layout: Use .WithWidth() (or size the Spectre widget itself) when the renderable should not flex to fill available space.
  3. Swap content with SetRenderable(): Reuse a single control and call SetRenderable() for live updates instead of recreating the control.
  4. Marshal background updates: Always call SetRenderable() on the UI thread via EnqueueOnUIThread when updating from timers or background tasks.
  5. Let the wheel bubble: Mouse-wheel events intentionally pass through to parent containers — place the control inside a scrollable panel for large renderables.
  6. Prefer MarkupControl for plain text: If you only need formatted text, MarkupControl is lighter weight; reserve this control for genuine Spectre widgets.

See Also

  • MarkupControl - For rich formatted text using SharpConsoleUI markup syntax

Back to Controls | Back to Main Documentation

Edit this page