flutter_layout_grid

The LayoutGrid can automatically place children when explicit positioning information is missing or partial. This behavior is controlled by the LayoutGrid.autoPlacement parameter and follows CSS Grid logic.

• No placement info: If a child is not wrapped in GridPlacement or NamedAreaGridPlacement, it is treated as a 1x1 widget and placed in the first available vacant cell.
• Partial placement info: If you provide some parameters (e.g., columnStart) but omit others (e.g., rowStart), the algorithm will search for the first vacant area that satisfies the provided constraints (e.g., finding the first available row in that specific column).

You can slice the grid into rectangular regions called areas using an ASCII-art string provided to the areas parameter. This follows the format of CSS grid-template-areas but uses a multiline string.

Important: If you provide an areas argument, you must ensure the number of elements in columnSizes and rowSizes matches the number of columns and rows defined in the ASCII art string.

Example of a 2-column, 3-row grid with named areas:

LayoutGrid(
  areas: '''
    header header
    nav    content
    footer footer
  '',
  columnSizes: [
    auto, // width for [nav, header, footer]
    1.fr, // width for [content, header, footer]
  ],
  rowSizes: [
    96.px, // height for [header]
    1.fr,  // height for [nav, content]
    72.px, // height for [footer]
  ],
  children: [
    // Children are assigned to areas using .inGridArea('name')
  ],
)

Add flutter_layout_grid to your pubspec.yaml dependencies to use the grid layout system in your Flutter project.

dependencies:
  flutter_layout_grid: ^2.0.0

When using the grid's auto-placement algorithm, you can choose between two packing strategies via the AutoPlacementPacking enum:

• sparse: The algorithm only moves "forward" in the grid. It never backtracks to fill holes, ensuring items appear in the order they are provided, even if this leaves empty spaces.
• dense: The algorithm attempts to fill holes earlier in the grid if smaller items appear later. This can result in items appearing out-of-order relative to their declaration if it helps fill gaps left by larger items.

enum AutoPlacementPacking {
  sparse,
  dense,
}

The autoPlacement property controls how items that are not explicitly positioned are flowed into the grid. It uses the AutoPlacement class to define the direction and packing behavior:

• AutoPlacement.rowSparse: Fills each row in turn, adding new rows as necessary.
• AutoPlacement.rowDense: Fills each row in turn, attempting to fill holes earlier in the grid with smaller items (may cause items to appear out-of-order).
• AutoPlacement.columnSparse: Fills each column in turn, adding new columns as necessary.
• AutoPlacement.columnDense: Fills each column in turn, attempting to fill holes earlier in the grid (may cause items to appear out-of-order).

// Example usage in LayoutGrid
LayoutGrid(
  columnSizes: [Flexible(), Flexible()],
  rowSizes: [Flexible(), Flexible()],
  autoPlacement: AutoPlacement.rowDense,
  children: [...],
)

Grid track sizes are defined using LayoutGrid.columnSizes and LayoutGrid.rowSizes. You can use three types of track sizes:

• Fixed: Occupies a specific number of pixels. Use FixedTrackSize(n), fixed(n), or n.px.
• Flexible: Fills remaining space after the initial layout. Use FlexibleTrackSize(n), flexible(n), or n.fr.
• Intrinsic Content: Sized to contain its items' contents and expands to fill available space after flexible tracks are calculated. Use IntrinsicContentTrackSize(), intrinsic(), or auto.

Example of a 4x3 grid:

LayoutGrid(
  columnSizes: [4.5.fr, 100.px, auto, 1.fr],
  rowSizes: [
    auto,
    100.px,
    1.fr,
  ],
)

If you have defined areas in your LayoutGrid, you can place children into those specific named regions using the NamedAreaGridPlacement widget or the inGridArea extension method.

Note: If a NamedAreaGridPlacement references an area name that does not exist in the grid's areas definition, the child will not be displayed. This behavior is useful for implementing responsive layouts where certain areas might disappear.

LayoutGrid(
  areas: '''
    red red blue
    red red blue
     .   .  blue
  ''',
  columnSizes: [64.px, 64.px, 64.px],
  rowSizes: [
    64.px,
    64.px,
    64.px,
  ],
  children: [
    // Using NamedAreaGridPlacement constructor
    NamedAreaGridPlacement(
      areaName: 'red',
      child: Container(color: Colors.red),
    ),
    // Alternatively, using the extension method:
    Container(color: Colors.red).inGridArea('red'),
  ],
)

To place a widget in a specific location within a LayoutGrid, wrap it in a GridPlacement widget or use the withGridPlacement extension method. You can specify the starting position and the number of cells to span using columnStart, columnSpan, rowStart, and rowSpan.

LayoutGrid(
  columnSizes: [1.fr, 1.fr, 1.fr, 1.fr],
  rowSizes: [
    1.fr,
    1.fr,
    1.fr,
  ],
  children: [
    GridPlacement(
      columnStart: 1,
      columnSpan: 3,
      rowStart: 0,
      rowSpan: 2,
      child: MyWidget(),
    ),
    // Alternatively, using the extension method:
    MyWidget().withGridPlacement(
      columnStart: 1,
      columnSpan: 3,
      rowStart: 0,
      rowSpan: 2,
    ),
  ],
)

While flutter_layout_grid implements many CSS Grid features, there are key differences to be aware of:

Unsupported features:

• Negative indexes: You cannot use negative values for row/column starts or ends to reference positions relative to the end of the axis.
• Out-of-bounds placement: Placing an item outside the explicit grid defined by your template rows/columns will throw an error.
• Advanced track sizing: minmax(), percentages, and aspect ratio track sizing are not currently supported.
• Content-based sizing: Unlike CSS, flexible tracks in flutter_layout_grid do not account for the base size of their content (for performance reasons).

Known limitations:

• Flexible tracks whose flex factors sum to less than 1.

The package provides extension methods on Widget to allow for more concise placement code.

• inGridArea(String areaName, {Key? key}): A shorthand for wrapping a widget in NamedAreaGridPlacement.
• withGridPlacement({Key? key, int? columnStart, int columnSpan = 1, int? rowStart, int rowSpan = 1}): A shorthand for wrapping a widget in GridPlacement.

// Using inGridArea
MyWidget().inGridArea('sidebar');

// Using withGridPlacement
MyWidget().withGridPlacement(columnStart: 1, columnSpan: 2);