NOTE: In v0.1, there was ambiguity with the use of the baseRows and baseColumns properties (stored on the target’s configuration) and use of values stored on the layout object. A breaking change has been made to the library meaning that baseRows and baseColumns are now deprecated. Additionally, the disallowExpansion property has been deprecated in favour of maxFlowAxis.

These properties will be removed in v0.3. Use layout.rows and layout.columns instead to set the initial size of the grid, and set maxFlowAxis to your row count to disable grid expansion.

Introduction

Flow grids are a dense grid layout, where widgets are placed relative to each other in an ordered manner. The configuration of the flow grid then determines the layout of the ordered widgets.

The layout property of a FlexiTarget’s configuration (see FlexiTarget) allows you to define a FlexiTarget that uses a flow layout. It is an object with the following properties:

export type FlowTargetLayout = {
	type: 'flow';
	placementStrategy: 'append' | 'prepend';
	disallowInsert?: boolean;
	flowAxis: 'row' | 'column';
	maxFlowAxis?: number;
	rows?: number;
	columns?: number;
};

• type: The type of layout to use, where flow defines a flow grid.
• placementStrategy: The strategy to use when placing widgets without coordinates into the grid (or when insertion is disallowed).
  • When set to append, widgets will be added to the end of the grid (default).
  • When set to prepend, widgets will be added to the beginning of the grid.
• disallowInsert: When set to true, widgets dropped in the grid will not be inserted based on the pointer position, and instead will use the placementStrategy.
• flowAxis: The axis that widgets are placed along.
• maxFlowAxis: The maximum number of widgets that can be placed along the flow axis.
• rows: The number of rows that the grid should have.
• columns: The number of columns that the grid should have.

Example

The following code creates us a basic flow grid with a list layout:

Extension to 2D

Flow grids can also enforce an ordered layout that spans two dimensions. When the cross dimension (in the opposite direction to your flow direction, i.e. columns for row flow and rows for column flow) is greater than 1, this occurs.

In this scenario, widgets will attempt to fill the cross dimension as much as possible, but they will also respect the order they’ve been put in. For example, in row flow, if a widget is unable to fit within its current row, it will leave a gap and span to the next row instead.

The below example demonstrates this behaviour, where we have a row flow grid with widgets of varying widths. Notice how widget B of width 2 is always placed on its own row, because when placed after A or C of width 1, it would not fit besides them on the grid.

Considerations

Flow grids have some main considerations:

• When providing the dimensions of a FlexiWidget that is part of a flow grid, any flow-axis dimension (width for column flow, height for row flow) provided is ignored. The flow-axis dimension is fixed to 1 in order to provide a consistent experience.
• However, when row/column sizing is set to auto or similar, you can have FlexiWidgets of different sizes on the flow axis, and the sizing of that cell will adjust for it.

More Examples

If you would like to see any further examples of flow grids in action, be sure to check out the open-source Notes (1D with nesting) and Flow (2D) examples, which are built using flow grids.

NB: If you have a better idea for an 2D flow grid example than ‘Flow’, please reach out and let us know! We’d love to have cool, real-world examples of Flexiboards in action.