Spectre.Console

Align Widget

Control horizontal and vertical alignment of content

The Align widget positions any renderable content within a defined space using horizontal and vertical alignment.

Screenshot

When to Use

Use Align when you need to position content within available space. Common scenarios:

  • Centering content: Create title screens, center tables or panels for visual emphasis
  • Right-aligned output: Align status information, timestamps, or metadata to the right edge
  • Vertical positioning: Position headers at the top, footers at the bottom, or center dialogs

For adding spacing around content, use Padder instead. For side-by-side layouts, use Columns or Grid.

Basic Usage

Create aligned content using the static factory methods Align.Left(), Align.Center(), or Align.Right().

csharp 
var panel = new Panel("Welcome to Spectre.Console!")
    .BorderColor(Color.Blue);
  
var centered = Align.Center(panel);
  
AnsiConsole.Write(centered);

Horizontal Alignment

Position content on the left, center, or right. Left alignment is the default for most widgets.

csharp 
var text = new Text("Left Aligned");
AnsiConsole.Write(Align.Left(text));
AnsiConsole.WriteLine();
  
text = new Text("Center Aligned");
AnsiConsole.Write(Align.Center(text));
AnsiConsole.WriteLine();
  
text = new Text("Right Aligned");
AnsiConsole.Write(Align.Right(text));

Vertical Alignment

Setting Vertical Position

Use vertical alignment with a specified height to position content vertically within a defined space.

csharp 
var text = new Text("Top Aligned").Centered();
var aligned = Align.Center(text, VerticalAlignment.Top)
    .Height(10);
  
AnsiConsole.Write(aligned);
AnsiConsole.MarkupLine("[grey]---[/]");
  
text = new Text("Middle Aligned").Centered();
aligned = Align.Center(text, VerticalAlignment.Middle)
    .Height(10);
  
AnsiConsole.Write(aligned);
AnsiConsole.MarkupLine("[grey]---[/]");
  
text = new Text("Bottom Aligned").Centered();
aligned = Align.Center(text, VerticalAlignment.Bottom)
    .Height(10);
  
AnsiConsole.Write(aligned);

Combining Alignments

Combine horizontal and vertical alignment to position content in both dimensions simultaneously.

csharp 
var content = new Panel("Centered in Both Directions")
    .BorderColor(Color.Green)
    .RoundedBorder();
  
var aligned = Align.Center(content, VerticalAlignment.Middle)
    .Height(15);
  
AnsiConsole.Write(aligned);

Using Extension Methods

Use the fluent extension methods like TopAligned(), MiddleAligned(), and BottomAligned() for more readable code.

csharp 
var panel = new Panel("Using Fluent Extensions")
    .BorderColor(Color.Yellow);
  
var aligned = Align.Left(panel)
    .MiddleAligned()
    .Height(8);
  
AnsiConsole.Write(aligned);

Controlling Dimensions

Width

By default, Align uses the content's natural width. Use Width() to define the alignment container's width.

csharp 
var text = new Markup("[bold blue]Auto Width[/]");
var autoWidth = Align.Center(text);
  
AnsiConsole.Write(autoWidth);
AnsiConsole.WriteLine();
  
text = new Markup("[bold green]Fixed Width (60)[/]");
var fixedWidth = Align.Center(text)
    .Width(60);
  
AnsiConsole.Write(fixedWidth);

Height

Set an explicit height with Height() when using vertical alignment to define the vertical space.

Practical Examples

Multiple Alignments

Create layouts with different horizontal alignments for visual variety or functional purpose.

csharp 
var leftPanel = new Panel("Left Panel")
    .BorderColor(Color.Red);
AnsiConsole.Write(Align.Left(leftPanel));
AnsiConsole.WriteLine();
  
var centerPanel = new Panel("Center Panel")
    .BorderColor(Color.Green);
AnsiConsole.Write(Align.Center(centerPanel));
AnsiConsole.WriteLine();
  
var rightPanel = new Panel("Right Panel")
    .BorderColor(Color.Blue);
AnsiConsole.Write(Align.Right(rightPanel));

Centering Tables

Center tables to draw focus and improve presentation for data displays.

csharp 
var table = new Table()
    .Border(TableBorder.Rounded)
    .BorderColor(Color.Purple)
    .AddColumn("Product")
    .AddColumn("Price");
  
table.AddRow("Coffee", "$3.50");
table.AddRow("Tea", "$2.50");
table.AddRow("Pastry", "$4.00");
  
var centered = Align.Center(table);
  
AnsiConsole.Write(centered);

Advanced Usage

Nested Alignment

Combine Align with containers like Panel to create multi-level alignment for complex layouts.

csharp 
var innerText = new Markup("[bold yellow]Inner Content[/]");
var innerPanel = new Panel(innerText)
    .BorderColor(Color.Yellow)
    .RoundedBorder();
  
var outerPanel = new Panel(Align.Center(innerPanel))
    .Header("[bold blue]Outer Container[/]")
    .BorderColor(Color.Blue)
    .Expand();
  
AnsiConsole.Write(outerPanel);

Title Screens

Use centered alignment for application splash screens or welcome messages.

csharp 
var title = new FigletText("Spectre")
    .Color(Color.Blue);
  
var subtitle = new Markup("[italic grey]A modern .NET console library[/]");
  
var titleAligned = Align.Center(title);
var subtitleAligned = Align.Center(subtitle);
  
AnsiConsole.Write(titleAligned);
AnsiConsole.Write(subtitleAligned);
AnsiConsole.WriteLine();
  
var instructions = new Markup("[dim]Press any key to continue...[/]");
AnsiConsole.Write(Align.Center(instructions));

See Also

API Reference

Represents a renderable used to align content.

Constructors

public Align(IRenderable renderable, HorizontalAlignment horizontal, VerticalAlignment? vertical = default)

Initializes a new instance of the Align class.

Parameters:

renderable (IRenderable)
The renderable to align.
horizontal (HorizontalAlignment)
The horizontal alignment.
vertical (VerticalAlignment?)
The vertical alignment, or null if none.

Properties

Height : int?

Gets or sets the height.

Horizontal : HorizontalAlignment

Gets or sets the horizontal alignment.

Vertical : VerticalAlignment?

Gets or sets the vertical alignment.

Width : int?

Gets or sets the width.

Methods

public static Align Center(IRenderable renderable, VerticalAlignment? vertical = default)

Initializes a new instance of the Align class that is center aligned.

Parameters:

renderable (IRenderable)
The IRenderable to align.
vertical (VerticalAlignment?)
The vertical alignment, or null if none.

Returns:

A new Align object.

public static Align Left(IRenderable renderable, VerticalAlignment? vertical = default)

Initializes a new instance of the Align class that is left aligned.

Parameters:

renderable (IRenderable)
The IRenderable to align.
vertical (VerticalAlignment?)
The vertical alignment, or null if none.

Returns:

A new Align object.

public static Align Right(IRenderable renderable, VerticalAlignment? vertical = default)

Initializes a new instance of the Align class that is right aligned.

Parameters:

renderable (IRenderable)
The IRenderable to align.
vertical (VerticalAlignment?)
The vertical alignment, or null if none.

Returns:

A new Align object.

Extension Methods

Align BottomAligned(this Align align)

Sets the Align object to be bottom aligned.

Returns:

The same instance so that multiple calls can be chained.

Align Height(this Align align, int? height)

Sets the height.

Returns:

The same instance so that multiple calls can be chained.

Align MiddleAligned(this Align align)

Sets the Align object to be middle aligned.

Returns:

The same instance so that multiple calls can be chained.

Align TopAligned(this Align align)

Sets the Align object to be top aligned.

Returns:

The same instance so that multiple calls can be chained.

Align VerticalAlignment(this Align align, VerticalAlignment? vertical)

Sets the vertical alignment.

Returns:

The same instance so that multiple calls can be chained.

Align Width(this Align align, int? width)

Sets the width.

Returns:

The same instance so that multiple calls can be chained.