Grid

A grid is a Columns count and a list of BitGridItem children. Each item fills a single column by default, so a four column grid puts four items on a row and wraps the rest onto the next one. The Span of the grid changes that default for all of its items at once, which is how a grid of uniform items states the span once instead of once per item.

Columns = 4 (each item fills one column)

Columns = 12, Span = 4 (the grid gives every item a span of 4, so 3 fit on a row)

ColumnSpan is how many columns of the grid a single item covers. The spans of a row are read against the column count of the grid, so in a 12 column grid a span of 6 is a half and a span of 4 is a third, and the items of a row line up on exactly the same tracks as the items of the row above no matter how the two are split. A span that asks for more columns than the grid has takes a full row rather than overflowing it.

Not every part of a row belongs on a column track. Auto makes an item exactly as wide as its own content and keeps it from growing or shrinking, which is what a label, an icon or a button next to a field wants. Grow does the opposite: the item takes whatever width is left over in its row, and the growing items of a row share that width equally.

An auto sized label, a growing field and an auto sized button

A fixed span next to two growing items, which share what is left equally

The Grow of the grid is the same thing asked of every item at once. A full row has nothing left over and is unchanged by it, so what it really decides is what the last row does: its items are widened until they fill it instead of leaving a hole where the missing items would have been. Items that are sized to their own content are left alone, since that is the whole of what they asked for - and an item that is only sized to its content at some sizes is left alone at those sizes alone.

Five items in a three column grid, first without and then with the Grow of the grid

Auto and Grow are responsive in the same mobile first way as the spans: AutoXs to AutoXxl and GrowXs to GrowXxl replace Auto and Grow from their own breakpoint upwards, and a value of false is how an item that had left the column tracks is given its columns back. That is what a label that is full width on a phone and only as wide as its text once its field fits beside it needs. Resize the window to watch these change.

The other way round: a row that leaves the tracks on a phone and lands back on them from Md

Offset leaves a number of columns empty before an item. The empty room is measured in the columns of the grid, gaps included, so an item offset by 2 starts exactly where the third column starts. This is how an item is indented, how a row is centered by pushing a single item away from the edge, and how a gap is left in the middle of a row without an empty item to hold it.

AutoOffset is the offset for the rows whose empty room cannot be counted in advance: instead of a number of columns, the item takes everything that is left before it and so lands against the end edge of its row. That is what a toolbar whose last button must sit on the far edge needs, and it keeps working when the items before it change their spans. It takes precedence over Offset.

Both kinds of offset are responsive and mobile first. OffsetXs to OffsetXxl change the number of columns per breakpoint, and AutoOffsetXs to AutoOffsetXxl turn the push to the end edge on and off per breakpoint, where false hands the room back to the counted offset. That is what an action that sits beside its heading on a desktop and stacks under it on a phone needs. Resize the window to watch these change.

Both of them leave their room on the edge the row starts at rather than on a fixed side of the screen, so they follow the text direction into a right-to-left grid and follow the flow into a Reversed one, where the row is laid out backwards and "before the item" is the other end.

Order decides where an item is painted regardless of where it is written. Items are laid out from the lowest order to the highest, and the ones that share an order keep the order they are written in, so a negative order moves a single item ahead of a group that left its order alone.

Only the painted order changes: a screen reader and the keyboard still walk the items in the order they are written in the markup, so reordering that leaves the two far apart makes the page harder to follow rather than easier.

HorizontalAlign shares out the width a row does not use, which is what a row whose spans do not add up to the column count leaves behind. Baseline and Stretch distribute nothing, so those two act on the vertical axis instead.

VerticalAlign is the other axis: a row is as tall as its tallest item, and this decides what the shorter ones do with the height left over. Stretch is what a row of cards that should all end on the same line wants, and Baseline lines up the first line of text of each item however tall the items themselves are.

AlignSelf pulls a single item out of the alignment of its row, which is what the action buttons of a form row that have to sit on the bottom edge need while every other item stays at the top. On the grid itself, Alignment is the shorthand that sets both axes at once, and HorizontalAlign and VerticalAlign each take precedence over it on their own axis.

The shorthand centering a row on both axes at once, and the same row taking its horizontal distribution from HorizontalAlign instead while the shorthand keeps the vertical one

AlignContent is the one alignment that moves the rows themselves rather than the items within a row, so it only shows up in a grid that wrapped onto more than one row and is taller than those rows needed. Every member means something here: Start, Center and End park the block of rows at one end of the grid, the three space distributions spread the rows apart, and Stretch grows the rows until they fill the height. It is not part of the Alignment shorthand.

Spacing is the room between the items on both axes, and HorizontalSpacing and VerticalSpacing each replace it on their own axis. The horizontal spacing is part of the width of every item: the free width of a row is what is left after the gaps between its items are taken out, and that remainder is what the columns divide up, so widening the spacing narrows the items instead of pushing them out of the row.

All three take any CSS length. A bare number is read as pixels, so Spacing="8" and Spacing="8px" are the same thing, and a fluid length such as Spacing="clamp(4px, 1vw, 16px)" lets the room between the items follow the size of the viewport without a breakpoint of its own.

A fluid spacing that grows with the viewport, from 4px on a phone up to 24px on a wide screen

All three are also responsive and mobile first: SpacingXs to SpacingXxl change the room on both axes from their own breakpoint upwards, and HorizontalSpacingXs to HorizontalSpacingXxl and VerticalSpacingXs to VerticalSpacingXxl refine a single axis there. That is the layout that is tight on a phone and given air on a desktop, written as the sizes at which the room actually changes. Resize the window to watch these change.

Rows that are given more room than the columns from the medium breakpoint upwards

The spacing is the one per breakpoint value that is still answered by the window inside a Container grid, since the room between the items belongs to the grid itself and an element cannot be measured against its own width. A spacing written in the container units - clamp(4px, 2cqw, 24px) - is what follows the width of the grid instead.

The grid takes a column count per breakpoint and every item takes a span, an offset and an order per breakpoint. All of them are mobile first: a value set at one breakpoint keeps applying to every wider one until another value replaces it, so a layout is described by the sizes at which it actually changes and not at every size in between. The breakpoints are Xs from 0px, Sm from 600px, Md from 960px, Lg from 1280px, Xl from 1920px and Xxl from 2560px.

Resize the window to watch these change.

Grid breakpoints: 2 columns on a phone, 3 from small, 4 from medium, 6 from large. Columns is the base of the chain, so it is the count of every breakpoint below the first one that is set.

Item breakpoints: a full width row on a phone that becomes a two thirds and one third layout

Offsets and orders are responsive in the same way. Here the sidebar is written after the content but painted before it up to the medium breakpoint, and the content is indented once there is room for it.

A span of 0 columns is an item that is not shown. Since the spans are responsive and mobile first like everything else, that is the whole of what is needed to drop a piece of a layout at one size and give it its columns back at another: ColumnSpan="0" Md="4" is a column that only appears once there is room for it, and ColumnSpan="6" Md="0" is one that only exists while the screen is narrow. Resize the window to watch these come and go.

An item can also be dropped for one band only, by hiding it at a breakpoint and giving it a span again at the next one: this one is gone between Sm and Md and shown on either side of that.

The item is still rendered into the page, only not painted, so this hides it from a screen reader as well and is not a way to keep content available to assistive technologies alone. An item that is sized to its content or asked to grow is never hidden this way either, since a width of its own has nothing to do with a count of columns.

MinItemWidth turns the question around. Instead of naming a number of columns per breakpoint, the grid is told the narrowest an item may be and simply fits as many equal items on a row as that allows, wrapping the rest onto the next one. The number of columns becomes a consequence of how much room there is, which is what a grid of cards of a known comfortable size wants: the cards decide the layout, and they keep deciding it in a page, a panel or a dialog without any of the three having to be told about the others.

It takes any CSS length, and a bare number is read as pixels. While it is set the column tracks are left behind, so Columns and the spans of the items no longer size anything - though an item that states Auto or Grow for itself is still sized the way it asked to be, at the breakpoints it asked for it at.

The items of a row always share it equally, which the last row of a grid shares out as well: a row that ends up holding a single item widens that item to the whole of it rather than leaving it at the width of one column. A short last row that should keep the width of the rows above it is a counted Columns layout rather than a fluid one.

An auto sized item keeps the width of its content while the rest of the row stays fluid

The breakpoints are measured against the window by default, which is the right answer for a page and the wrong one for a piece of a page: a grid inside a narrow panel is still told that the window is wide, and lays out four columns in the room for one. Container makes the grid a CSS query container and measures every one of its breakpoints - the column counts, the spans, the offsets, the orders, the sizing and the hiding - against the width of the grid itself instead.

The breakpoints keep their usual widths, so a grid in a 700px panel lays itself out the way the same grid lays itself out in a 700px window. That is what lets one component carry its own layout into every place it is used rather than being told about each of them.

Drag the handle in the bottom right corner of each box to resize it.

A query container is also the containing block of the absolutely positioned elements inside it, and its width can no longer be worked out from its content, which is why this is asked for rather than assumed. Grids inside grids each answer for their own items, so a container grid nested in another one is measured against itself and not against its parent.

A grid wraps by default: an item that no longer fits on a row moves to the next one. NoWrap keeps every item on a single row and shrinks them to fit instead, which is what a toolbar or a summary strip that must never break wants.

Six items in a four column grid, wrapping (the default)

The same six items with NoWrap

Reversed paints the items from the end edge of the grid backwards. Only the painting is reversed: the items are still read and reached in the order they are written. Reversing swaps the edge the row starts at, so HorizontalAlign Start now packs the items against the right of a left-to-right grid, and an Offset or an AutoOffset leaves its room on that same right edge, since the room they leave is the room before the item in the order the row is laid out in.

A grid inside a grid item divides the width of that item, not the width of the page, and it starts from its own column count rather than inheriting the one of its parent. That is what lets a section of a layout be split into its own proportions without any of the numbers of the outer grid having to be recalculated.

The root of the grid and of its items is a div by default. Element replaces that tag with any other one, which is how a grid of things that form a list becomes a real ul of li elements, or how a grid that is a region of the page becomes a section. The layout is unaffected: only the tag name changes, and with it what assistive technologies report.

A list whose bullets are removed loses its list semantics in some screen readers, so a grid that is rendered as a ul is worth handing an explicit role="list" through its html attributes, exactly as a hand written list would be.

The parameters are worth more together than apart. These are the three layouts almost every page is built from, each of them written with the piece of the grid that fits it best.

A form row: an Auto label that is exactly as wide as its text, a Grow field that takes the rest of the row, and an Auto action next to it. Nothing here is counted in columns, so the row keeps working as the labels change, which is why each row is a grid of its own.

A page shell: a full width header, a sidebar and a content area that stack on a phone and sit side by side from the medium breakpoint, and a full width footer. The sidebar is written after the content and painted before it while the two are stacked, so the content stays first in the reading order, and the breadcrumb is dropped entirely while there is no room for it.

A toolbar: a title that grows, a group of actions pushed to the far edge by AutoOffset, and NoWrap so the strip never breaks onto a second line however narrow it gets.

A card gallery: no breakpoints at all, just the narrowest a card may be. The row holds as many cards as fit at that width and shares itself equally between them, so the gallery answers to the room it is given in a page, a panel or a dialog without being told about any of the three.

The Style and Class of the grid and of its items land on their root elements, next to everything the component itself renders there. The layout is driven by inline custom properties, so a class of your own is free to paint an item however it likes without ever fighting the sizing.

In a right-to-left grid the start edge is the right one, so the items are laid out from the right, HorizontalAlign packs them against the right edge, and an Offset indents an item from the right. The spans themselves are unchanged: the columns are the same tracks, counted from the other side.