Spectre.Console

Layout Widget

Create complex multi-section layouts with the flexible Layout widget

The Layout widget divides console space into sections that can be split horizontally or vertically, enabling complex multi-region interfaces.

Screenshot

When to Use

Use Layout when you need to divide the console into distinct regions with precise control over sizing. Common scenarios:

  • Dashboard interfaces: Headers, sidebars, content areas, and footers with fixed or proportional sizing
  • Multi-pane views: Split screen layouts like file managers, IDE-style interfaces, or monitoring dashboards
  • Responsive layouts: Sections that adapt proportionally to available space using ratios

For simple side-by-side content without nested regions, use Columns instead. For tabular data with borders, use Grid.

Basic Usage

Split a layout into columns or rows, then update each section by name.

public static void BasicLayoutExample()
{
    var layout = new Layout("Root")
        .SplitColumns(
            new Layout("Left"),
            new Layout("Right"));
  
    layout["Left"].Update(
        new Panel("Left Panel")
            .BorderColor(Color.Green));
  
    layout["Right"].Update(
        new Panel("Right Panel")
            .BorderColor(Color.Blue));
  
    AnsiConsole.Write(layout);
}

Accessing Sections by Name

Use named sections to access and update specific regions, making your layout easier to manage and modify.

public static void LayoutNavigationExample()
{
    var layout = new Layout("Root")
        .SplitColumns(
            new Layout("Left"),
            new Layout("Center"),
            new Layout("Right"));
  
    // Update sections individually by name
    layout["Left"].Update(new Markup("[blue]Navigation[/]"));
    layout["Center"].Update(new Markup("[green]Main Content[/]"));
    layout["Right"].Update(new Markup("[yellow]Sidebar[/]"));
  
    AnsiConsole.Write(layout);
}

Splitting into Rows

Use SplitRows() to create vertical sections like headers, content areas, and footers.

public static void LayoutRowsExample()
{
    var layout = new Layout("Root")
        .SplitRows(
            new Layout("Top"),
            new Layout("Bottom"));
  
    layout["Top"].Update(
        new Panel("Header Section")
            .Header("Top")
            .BorderColor(Color.Yellow));
  
    layout["Bottom"].Update(
        new Panel("Content Section")
            .Header("Bottom")
            .BorderColor(Color.Cyan1));
  
    AnsiConsole.Write(layout);
}

Size Control

Fixed Sizes

Use Size() to set exact widths or heights for sections that need consistent dimensions, like sidebars or headers.

public static void LayoutFixedSizeExample()
{
    var layout = new Layout("Root")
        .SplitColumns(
            new Layout("Sidebar").Size(20),
            new Layout("Content"));
  
    layout["Sidebar"].Update(
        new Panel("Fixed\n20 chars\nwide")
            .BorderColor(Color.Purple));
  
    layout["Content"].Update(
        new Panel("This section takes remaining space")
            .BorderColor(Color.Green));
  
    AnsiConsole.Write(layout);
}

Proportional Sizing with Ratios

Use Ratio() to distribute space proportionally when sections should scale relative to each other.

public static void LayoutRatioExample()
{
    var layout = new Layout("Root")
        .SplitColumns(
            new Layout("Left").Ratio(1),
            new Layout("Center").Ratio(2),
            new Layout("Right").Ratio(1));
  
    layout["Left"].Update(new Panel("1/4 width").BorderColor(Color.Blue));
    layout["Center"].Update(new Panel("2/4 width (half)").BorderColor(Color.Green));
    layout["Right"].Update(new Panel("1/4 width").BorderColor(Color.Yellow));
  
    AnsiConsole.Write(layout);
}

Minimum Sizes

Use MinimumSize() to ensure sections remain readable even when space is constrained.

public static void LayoutMinimumSizeExample()
{
    var layout = new Layout("Root")
        .SplitColumns(
            new Layout("Navigation").MinimumSize(15),
            new Layout("Content"));
  
    layout["Navigation"].Update(
        new Panel("Navigation\nMin 15 chars")
            .BorderColor(Color.Cyan1));
  
    layout["Content"].Update(
        new Panel("Content area that flexes")
            .BorderColor(Color.Green));
  
    AnsiConsole.Write(layout);
}

Advanced Usage

Nested Layouts

Create complex multi-level layouts by splitting sections recursively to build sophisticated interfaces.

public static void LayoutNestedExample()
{
    var layout = new Layout("Root")
        .SplitRows(
            new Layout("Header").Size(3),
            new Layout("Body"),
            new Layout("Footer").Size(3));
  
    layout["Header"].Update(
        new Panel("[yellow]Application Header[/]")
            .BorderColor(Color.Yellow));
  
    layout["Body"].SplitColumns(
        new Layout("Sidebar").Size(20),
        new Layout("Content"));
  
    layout["Sidebar"].Update(
        new Panel("[blue]Menu[/]\n• Home\n• Settings\n• About")
            .BorderColor(Color.Blue));
  
    layout["Content"].Update(
        new Panel("[green]Main Content Area[/]")
            .BorderColor(Color.Green));
  
    layout["Footer"].Update(
        new Panel("[grey]Status Bar[/]")
            .BorderColor(Color.Grey));
  
    AnsiConsole.Write(layout);
}

Dashboard Layout

Combine multiple layout techniques to create a complete dashboard with headers, sidebars, content areas, and status bars.

public static void LayoutDashboardExample()
{
    var layout = new Layout("Root")
        .SplitRows(
            new Layout("Header").Size(3),
            new Layout("Main"),
            new Layout("Footer").Size(3));
  
    layout["Header"].Update(
        new Panel("[bold yellow]System Dashboard[/]")
            .BorderColor(Color.Yellow));
  
    layout["Main"].SplitColumns(
        new Layout("Left").Ratio(1),
        new Layout("Right").Ratio(2));
  
    layout["Left"].SplitRows(
        new Layout("Metrics"),
        new Layout("Logs"));
  
    layout["Metrics"].Update(
        new Panel("[green]CPU: 45%\nRAM: 62%\nDisk: 78%[/]")
            .Header("System Metrics")
            .BorderColor(Color.Green));
  
    layout["Logs"].Update(
        new Panel("[dim]12:03 Process started\n12:05 Connected\n12:07 Ready[/]")
            .Header("Recent Logs")
            .BorderColor(Color.Blue));
  
    layout["Right"].Update(
        new Panel("[white]Main application content area\nDisplays real-time data and visualizations[/]")
            .Header("Content")
            .BorderColor(Color.Cyan1));
  
    layout["Footer"].Update(
        new Panel("[dim]Connected | Uptime: 2h 34m | Last Update: 12:07:45[/]")
            .BorderColor(Color.Grey));
  
    AnsiConsole.Write(layout);
}

Three-Column Layout

Create a classic application layout with navigation, main content, and sidebar regions containing different widget types.

public static void LayoutThreeColumnExample()
{
    var layout = new Layout("Root")
        .SplitColumns(
            new Layout("Navigation").Size(18),
            new Layout("Main"),
            new Layout("Sidebar").Size(22));
  
    layout["Navigation"].Update(
        new Panel(new Markup(
            "[blue]Menu[/]\n" +
            "├─ Dashboard\n" +
            "├─ Reports\n" +
            "└─ Settings"))
            .BorderColor(Color.Blue));
  
    var table = new Table()
        .BorderColor(Color.Green)
        .AddColumn("Item")
        .AddColumn("Value")
        .AddRow("Orders", "1,234")
        .AddRow("Revenue", "$45,678");
  
    layout["Main"].Update(
        new Panel(table)
            .Header("Statistics")
            .BorderColor(Color.Green));
  
    layout["Sidebar"].Update(
        new Panel("[yellow]Quick Actions[/]\n• New Report\n• Export Data\n• Refresh")
            .BorderColor(Color.Yellow));
  
    AnsiConsole.Write(layout);
}

Dynamic Visibility

Control section visibility at runtime to show or hide regions based on application state.

public static void LayoutVisibilityExample()
{
    var layout = new Layout("Root")
        .SplitColumns(
            new Layout("Left"),
            new Layout("Middle"),
            new Layout("Right"));
  
    layout["Left"].Update(new Panel("Always visible").BorderColor(Color.Green));
    layout["Middle"].Update(new Panel("Hidden section").BorderColor(Color.Red));
    layout["Right"].Update(new Panel("Also visible").BorderColor(Color.Blue));
  
    // Hide the middle section
    layout["Middle"].IsVisible = false;
  
    AnsiConsole.Write(layout);
}

Dynamic Content Updates

Update section content in response to events or state changes for interactive interfaces.

public static void LayoutDynamicUpdateExample()
{
    var layout = new Layout("Root")
        .SplitColumns(
            new Layout("Status"),
            new Layout("Content"));
  
    // Initial state
    layout["Status"].Update(
        new Panel("[yellow]Loading...[/]")
            .BorderColor(Color.Yellow));
  
    layout["Content"].Update(
        new Panel("Waiting for data...")
            .BorderColor(Color.Grey));
  
    // Simulate update (in real use, you'd re-render)
    layout["Status"].Update(
        new Panel("[green]Ready[/]")
            .BorderColor(Color.Green));
  
    layout["Content"].Update(
        new Panel("Data loaded successfully!")
            .BorderColor(Color.Green));
  
    AnsiConsole.Write(layout);
}

API Reference

Represents a renderable to divide a fixed height into rows or columns.

Constructors

Layout(string name)

Initializes a new instance of the class.

Parameters:

name (string)
The layout name.
Layout(IRenderable renderable)

Initializes a new instance of the class.

Parameters:

renderable (IRenderable)
The renderable.
Layout(string name, IRenderable renderable)

Initializes a new instance of the class.

Parameters:

name (string)
The layout name.
renderable (IRenderable)
The renderable.

Properties

IsVisible : bool

Gets or sets a value indicating whether or not the layout should be visible or not.

Item : Layout
MinimumSize : int

Gets or sets the minimum width.

Name : string

Gets or sets the name.

Ratio : int

Gets or sets the ratio.

Size : Nullable<int>

Gets or sets the width.

Methods

Layout GetLayout(string name)

Gets a child layout by it's name.

Parameters:

name (string)
The layout name.

Returns:

The specified child .

Layout SplitColumns(Layout[] children)

Splits the layout into columns.

Parameters:

children (Layout[])
The layout to split into columns.

Returns:

The same instance so that multiple calls can be chained.

Layout SplitRows(Layout[] children)

Splits the layout into rows.

Parameters:

children (Layout[])
The layout to split into rows.

Returns:

The same instance so that multiple calls can be chained.

Layout Update(IRenderable renderable)

Updates the containing .

Parameters:

renderable (IRenderable)
The renderable to use for this layout.

Returns:

The same instance so that multiple calls can be chained.

Extension Methods

IEnumerable<Segment> GetSegments(IAnsiConsole console)

Gets the segments for a renderable using the specified console.

Parameters:

console (IAnsiConsole)
The console.

Returns:

An enumerable containing segments representing the specified .

Layout MinimumSize(int size)

Sets the minimum width of the layout.

Parameters:

size (int)
The size.

Returns:

The same instance so that multiple calls can be chained.

Layout Ratio(int ratio)

Sets the ratio of the layout.

Parameters:

ratio (int)
The ratio.

Returns:

The same instance so that multiple calls can be chained.

Layout Size(int size)

Sets the size of the layout.

Parameters:

size (int)
The size.

Returns:

The same instance so that multiple calls can be chained.