Spectre.Console Documentation

The Grid widget arranges content in rows and columns without visible borders, providing flexible layouts for console applications.

When to Use

Use Grid when you need to arrange content in invisible columns without the visual structure of borders. Common scenarios:

Configuration displays: Property names and values, settings lists, key-value pairs
Dashboard layouts: Arranging panels, charts, or widgets in columns
Form-like output: Labels aligned with corresponding data
Multi-column text: Side-by-side content without table borders

For structured data with visible borders, use Table instead. For automatically flowing items into columns, use Columns which handles wrapping and sizing automatically.

Basic Usage

Add columns first, then populate rows with content. Each row must have the same number of cells as columns.

public static void BasicGridExample()
{
    var grid = new Grid();
  
    // Add columns
    grid.AddColumn();
    grid.AddColumn();
  
    // Add rows
    grid.AddRow("Name:", "[blue]John Doe[/]");
    grid.AddRow("Email:", "[blue]john.doe@example.com[/]");
    grid.AddRow("Phone:", "[blue]+1 (555) 123-4567[/]");
  
    AnsiConsole.Write(grid);
}

Column Configuration

Column Widths

Use fixed widths to control column sizing precisely, or omit width for auto-sizing based on content.

public static void GridColumnWidthExample()
{
    var grid = new Grid();
  
    // Add columns with explicit widths
    grid.AddColumn(new GridColumn { Width = 15 });
    grid.AddColumn(new GridColumn { Width = 40 });
  
    grid.AddRow("[yellow]Label Column[/]", "[green]Content Column[/]");
    grid.AddRow("Short", "This column has a fixed width of 40 characters");
    grid.AddRow("Status", "Active");
  
    AnsiConsole.Write(grid);
}

Alignment

Align content within columns using Justify.Left, Justify.Right, or Justify.Center. Right-align numeric data for easier comparison.

public static void GridAlignmentExample()
{
    var grid = new Grid();
  
    // Right-align the first column, left-align the second
    grid.AddColumn(new GridColumn { Alignment = Justify.Right });
    grid.AddColumn(new GridColumn { Alignment = Justify.Left });
  
    grid.AddRow("Amount:", "$1,234.56");
    grid.AddRow("Tax:", "$123.46");
    grid.AddRow("Total:", "[bold green]$1,358.02[/]");
  
    AnsiConsole.Write(grid);
}

Padding

Control spacing between columns with custom padding. Adjust the right padding to increase or decrease column separation.

public static void GridPaddingExample()
{
    var grid = new Grid();
  
    // Add columns with custom padding
    grid.AddColumn(new GridColumn { Padding = new Padding(0, 0, 4, 0) });
    grid.AddColumn(new GridColumn { Padding = new Padding(0, 0, 2, 0) });
    grid.AddColumn(new GridColumn());
  
    grid.AddRow("[yellow]Wide[/]", "[blue]Normal[/]", "[green]Default[/]");
    grid.AddRow("Col 1", "Col 2", "Col 3");
  
    AnsiConsole.Write(grid);
}

Preventing Text Wrap

Use NoWrap when content should be truncated rather than wrapped to multiple lines.

public static void GridNoWrapExample()
{
    var grid = new Grid();
  
    grid.AddColumn(new GridColumn { NoWrap = true, Width = 20 });
    grid.AddColumn(new GridColumn());
  
    grid.AddRow(
        "This is a very long label that would normally wrap",
        "Value");
  
    AnsiConsole.Write(grid);
}

Grid Layout

Expanding to Fill Width

Use Expand = true to make the grid fill available console width—useful for dashboards or full-width layouts.

public static void GridExpandExample()
{
    var grid = new Grid { Expand = true };
  
    grid.AddColumn();
    grid.AddColumn();
  
    grid.AddRow("[yellow]Left[/]", "[cyan]Right[/]");
    grid.AddRow("This grid expands", "to fill the console");
  
    AnsiConsole.Write(grid);
}

Fixed Grid Width

Constrain the entire grid to a specific width when you need precise sizing.

public static void GridWidthExample()
{
    var grid = new Grid();
    grid.Width(60);
  
    grid.AddColumn();
    grid.AddColumn();
  
    grid.AddRow("[yellow]Fixed Width[/]", "[cyan]Grid[/]");
    grid.AddRow("This grid is", "exactly 60 characters wide");
  
    AnsiConsole.Write(grid);
}

Working with Rows

Empty Rows

Insert empty rows to create visual separation between groups of content.

public static void GridEmptyRowsExample()
{
    var grid = new Grid();
  
    grid.AddColumn();
    grid.AddColumn();
  
    grid.AddRow("[yellow]Section 1[/]", "");
    grid.AddRow("Item A", "Value A");
    grid.AddRow("Item B", "Value B");
    grid.AddEmptyRow();
    grid.AddRow("[yellow]Section 2[/]", "");
    grid.AddRow("Item C", "Value C");
    grid.AddRow("Item D", "Value D");
  
    AnsiConsole.Write(grid);
}

Adding Multiple Columns

Use the AddColumns() extension method to quickly add several columns at once.

public static void GridAddColumnsExample()
{
    var grid = new Grid();
  
    // Add 4 columns at once
    grid.AddColumns(4);
  
    grid.AddRow("[red]Q1[/]", "[green]Q2[/]", "[blue]Q3[/]", "[yellow]Q4[/]");
    grid.AddRow("$10,000", "$12,500", "$11,000", "$15,000");
  
    AnsiConsole.Write(grid);
}

Advanced Usage

Nested Content

Embed other widgets like Panels, Charts, or Progress bars within grid cells for rich layouts.

public static void GridNestedContentExample()
{
    var grid = new Grid();
  
    grid.AddColumn();
    grid.AddColumn();
  
    var leftPanel = new Panel("[yellow]Configuration[/]")
        .BorderColor(Color.Yellow)
        .RoundedBorder();
  
    var rightPanel = new Panel("[green]Status: Active[/]")
        .BorderColor(Color.Green)
        .RoundedBorder();
  
    grid.AddRow(leftPanel, rightPanel);
  
    AnsiConsole.Write(grid);
}

Complex Layouts

Combine multiple features to create sophisticated layouts with mixed content types.

public static void GridComplexLayoutExample()
{
    var grid = new Grid();
  
    // Configure columns
    grid.AddColumn(new GridColumn { Width = 20, Alignment = Justify.Right });
    grid.AddColumn(new GridColumn());
  
    // Add header
    grid.AddRow(
        new Text("System Information", new Style(Color.Yellow, decoration: Decoration.Bold)),
        new Text(""));
  
    grid.AddEmptyRow();
  
    // Add data rows
    grid.AddRow(new Markup("OS:"), new Markup("[blue]Linux[/]"));
    grid.AddRow(new Markup("CPU:"), new Markup("[green]8 cores @ 3.2GHz[/]"));
    grid.AddRow(
        new Markup("Memory:"),
        new BreakdownChart()
            .Width(40)
            .AddItem("Used", 12, Color.Red)
            .AddItem("Available", 4, Color.Green));
    grid.AddRow(
        new Markup("Disk:"),
        new Panel("[yellow]65% used[/]")
            .BorderColor(Color.Yellow));
  
    AnsiConsole.Write(grid);
}

Dashboard Layouts

Create multi-level layouts by nesting grids to build complex dashboard-style interfaces.

public static void GridDashboardExample()
{
    // Create main grid
    var mainGrid = new Grid { Expand = true };
    mainGrid.AddColumn();
  
    // Create header
    var header = new Panel("[bold yellow]System Dashboard[/]")
        .BorderColor(Color.Yellow)
        .RoundedBorder();
  
    mainGrid.AddRow(header);
    mainGrid.AddEmptyRow();
  
    // Create metrics grid
    var metricsGrid = new Grid();
    metricsGrid.AddColumns(3);
  
    var cpuPanel = new Panel("[green]CPU: 45%[/]")
        .Header("Processor")
        .BorderColor(Color.Green);
  
    var memPanel = new Panel("[yellow]Memory: 8.2GB[/]")
        .Header("RAM")
        .BorderColor(Color.Yellow);
  
    var diskPanel = new Panel("[red]Disk: 85%[/]")
        .Header("Storage")
        .BorderColor(Color.Red);
  
    metricsGrid.AddRow(cpuPanel, memPanel, diskPanel);
  
    mainGrid.AddRow(metricsGrid);
  
    AnsiConsole.Write(mainGrid);
}

API Reference

A renderable grid.

Constructors

Grid()

Initializes a new instance of the class.

Properties

Alignment : Nullable<Justify>

Columns : IReadOnlyList<GridColumn>

Gets the grid columns.

Expand : bool

Rows : IReadOnlyList<GridRow>

Gets the grid rows.

Width : Nullable<int>

Gets or sets the width of the grid.

Methods

Grid AddColumn()

Adds a column to the grid.

Returns:

The same instance so that multiple calls can be chained.

Grid AddColumn(GridColumn column)

Adds a column to the grid.

Parameters:

column (GridColumn)

The column to add.

Returns:

The same instance so that multiple calls can be chained.

Grid AddRow(IRenderable[] columns)

Adds a new row to the grid.

Parameters:

columns (IRenderable[])

The columns to add.

Returns:

The same instance so that multiple calls can be chained.

Extension Methods

Grid AddColumns(int count)

Adds a column to the grid.

Parameters:

count (int)

The number of columns to add.

Returns:

The same instance so that multiple calls can be chained.

Grid AddColumns(GridColumn[] columns)

Adds a column to the grid.

Parameters:

columns (GridColumn[])

The columns to add.

Returns:

The same instance so that multiple calls can be chained.

Grid AddEmptyRow()

Adds an empty row to the grid.

Returns:

The same instance so that multiple calls can be chained.

Grid AddRow(String[] columns)

Adds a new row to the grid.

Parameters:

columns (String[])

The columns to add.

Returns:

The same instance so that multiple calls can be chained.

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 .

Grid Width(Nullable<int> width)

Sets the grid width.

Parameters:

width (Nullable<int>)

The width.

Returns:

The same instance so that multiple calls can be chained.