grid

Function

grid(
    states: list[State],
    rows: Optional[int] = None,
    cols: Optional[int] = None,
    spacing_h: float = 100,
    spacing_v: float = 100,
    center: Point2D = Point2D(x=0, y=0),
    alignment: ElementAlignment = <ElementAlignment.PRESERVE: 'preserve'>,
    element_rotation_offset: float = 0
) -> list[State]

Arrange states in a rectangular grid formation.

Positions elements in a grid with configurable spacing, center, and alignment. If rows or cols are not provided, the function will attempt to create a nearly square grid. Preserves all other state attributes (color, scale, opacity, etc.) while only modifying x and y positions.

Parameters

states: List of states to arrange
rows: Number of rows in the grid (optional)
cols: Number of columns in the grid (optional)
spacing_h: Horizontal spacing between elements
spacing_v: Vertical spacing between elements
cx: X coordinate of grid center
cy: Y coordinate of grid center
alignment: How to align each element relative to the grid. PRESERVE keeps original rotation, LAYOUT aligns with grid axes, UPRIGHT starts from vertical position.
element_rotation_offset: Additional rotation in degrees added to the alignment base.

Returns

New list of states with grid positions