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().

public static void BasicAlignExample()
{
    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.

public static void HorizontalAlignmentExample()
{
    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.

public static void VerticalAlignmentExample()
{
    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.

public static void CombinedAlignmentExample()
{
    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.

public static void FluentExtensionsExample()
{
    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.

public static void WidthControlExample()
{
    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.

public static void MultipleAlignmentsExample()
{
    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.

public static void AlignTableExample()
{
    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.

public static void NestedAlignExample()
{
    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.

public static void TitleScreenExample()
{
    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));
}

API Reference

Represents a renderable used to align content.

Constructors

Align(IRenderable renderable, HorizontalAlignment horizontal, Nullable<VerticalAlignment> vertical)

Initializes a new instance of the class.

Parameters:

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

Properties

Height : Nullable<int>

Gets or sets the height.

Horizontal : HorizontalAlignment

Gets or sets the horizontal alignment.

Vertical : Nullable<VerticalAlignment>

Gets or sets the vertical alignment.

Width : Nullable<int>

Gets or sets the width.

Extension Methods

Align BottomAligned()

Sets the object to be bottom aligned.

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 .

Align Height(Nullable<int> height)

Sets the height.

Parameters:

height (Nullable<int>)
The height, or null for no explicit height.

Returns:

The same instance so that multiple calls can be chained.

Align MiddleAligned()

Sets the object to be middle aligned.

Returns:

The same instance so that multiple calls can be chained.

Align TopAligned()

Sets the object to be top aligned.

Returns:

The same instance so that multiple calls can be chained.

Align VerticalAlignment(Nullable<VerticalAlignment> vertical)

Sets the vertical alignment.

Parameters:

vertical (Nullable<VerticalAlignment>)
The vertical alignment, or null for no vertical alignment.

Returns:

The same instance so that multiple calls can be chained.

Align Width(Nullable<int> width)

Sets the width.

Parameters:

width (Nullable<int>)
The width, or null for no explicit width.

Returns:

The same instance so that multiple calls can be chained.