How Rich Align and Alignment Methods Work for Centering and Padding Content

Rich's Align class positions renderables within available console dimensions by calculating excess space and injecting styled Segment objects containing spaces on the left, right, top, or bottom sides of the content.

The Align class in Textualize/rich provides precise control over content positioning through horizontal and vertical alignment algorithms. By wrapping any renderable object, it calculates available space and distributes padding segments to achieve left, center, right, top, middle, or bottom positioning within specified width and height constraints.

Horizontal Alignment Implementation in rich/align.py

Inside Align.__rich_console__, the algorithm first measures the inner renderable to determine the excess_space (calculated as options.max_width - width). This value represents the spare columns available for distribution as padding.

Left Alignment

For left alignment, the class pads the right side with Segment(" " * excess_space, style) when self.pad is True. This pushes the content to the left edge while filling the remaining line width with styled spaces.

Center Alignment

Center mode splits excess_space into left = excess_space // 2 and the remainder for the right side. The method yields a left Segment containing the calculated spaces, followed by the content, then an optional right Segment containing the remaining spaces. This integer division ensures the content sits visually centered even with odd-numbered excess columns.

Right Alignment

For right alignment, the class pads the left side with a single Segment(" " * excess_space, style), pushing the content flush against the right edge of the available width.

Vertical Alignment and Height Constraints

When self.vertical is specified, the rendered lines are wrapped with blank_lines(count) calls before or after the content based on the selected mode (top, middle, bottom). The height defaults to the console height or respects a user-provided height parameter. This logic is implemented in Align.__rich_console__ (lines 111-131 in rich/align.py).

Padding Control with the pad Parameter

The pad boolean flag controls whether trailing spaces are added to fill the entire line width. When pad=False, right-hand padding is disabled for left-aligned output, and trailing right-hand padding is removed for centered output. This allows precise control over whitespace generation without affecting the alignment position itself, as seen in the left/center branches (lines 68-84).

Styling Background Spaces

If a style is supplied, console.get_style converts it into a Style object. The generated space segments inherit this style, and Segment.apply_style decorates the entire output when self.style is truthy. This ensures background colors and attributes extend uniformly through the padded regions, creating solid colored blocks around content.

Width Constraints and Content Limits

The self.width parameter limits the inner renderable's width using min(width, self.width) logic (lines 48-52 in rich/align.py). This prevents content from exceeding specified boundaries while maintaining alignment calculations based on the constrained dimensions. The rich/constrain.py module provides underlying utilities for enforcing these width limits.

Convenient Class Methods

Instead of instantiating Align directly with the align parameter, use these factory methods defined in rich/align.py (lines 77-106):

• Align.left() – Pre-sets horizontal alignment to left
• Align.center() – Pre-sets horizontal alignment to center
• Align.right() – Pre-sets horizontal alignment to right

These thin wrappers simplify code readability while maintaining identical underlying functionality to the main class constructor.

Practical Usage Examples

from rich.console import Console
from rich.align import Align
from rich.panel import Panel

console = Console(width=30)

# Simple left, centre, right alignment

console.print(Align("left side", "left"))
console.print(Align("centre", "center"))
console.print(Align("right side", "right"))

# Adding a background style and disabling right‑hand padding

console.print(Align("styled", "center", style="on blue", pad=False))

# Vertical centering inside a fixed height region

panel = Panel("Centered vertically", width=20, height=5)
console.print(Align(panel, "center", vertical="middle", height=10))

# Limiting the maximum width of the aligned content

long_text = "A very long line that will be wrapped by Align"
console.print(Align(long_text, "center", width=25))

These patterns correspond directly to the test assertions in tests/test_align.py, which validates all combinations of horizontal, vertical, style, padding, width, and height parameters.

Summary

• Align calculates excess_space by subtracting content width from available console width in __rich_console__
• Horizontal positioning distributes space segments to left, right, or both sides depending on alignment mode
• Vertical alignment injects blank lines above or below content using blank_lines() when vertical is specified
• The pad parameter controls whether trailing whitespace segments are generated on the right side
• Style inheritance through console.get_style ensures padded regions maintain background colors
• Factory methods Align.left(), Align.center(), and Align.right() provide convenient instantiation shortcuts
• Width constraints use min(width, self.width) to limit inner renderable dimensions before alignment calculations

Frequently Asked Questions

How does Rich's Align class calculate centering positions?

The Align class determines centering by calculating excess_space = options.max_width - width, then splitting this value using integer division (excess_space // 2) to determine left padding, with the remainder applied to the right side. This ensures the content sits visually centered within the available console width, as implemented in rich/align.py.

What is the difference between pad=True and pad=False in Rich Align?

When pad=True (default), Align generates space segments for both sides of the content, ensuring the rendered output occupies the full available width. When pad=False, trailing right-hand padding is omitted, resulting in tighter output that may not fill the entire line width but maintains the correct left-side positioning for alignment purposes.

Can Align handle both horizontal and vertical centering simultaneously?

Yes, by specifying both align="center" and vertical="middle" parameters, Align applies horizontal centering through left/right space segments and vertical centering through blank_lines() injected before and after the content. This effectively centers the renderable within a two-dimensional region defined by width and height constraints.

Where does Rich store the alignment logic for width constraints?

Width constraint logic resides in rich/align.py within the __rich_console__ method (lines 48-52), where self.width is applied using min(width, self.width) to limit the inner renderable's dimensions before alignment calculations occur. Additional segment generation logic uses the Segment class from rich/segment.py to create the actual padding content.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}