{
"name": "Grid",
"source": "src/components/Grid.tsx",
"propsType": "GridProps",
"description": "Grid — columns that line up across rows, gaps from the spacing scale.\n\nWhere Stack lays things along one line, Grid keeps every row's columns\nthe same width: cards, stat tiles, a main column and its aside, a form in\ntwo columns. Every track is `minmax(0, …)`, so one wide child — a table, a\nlong ID — cannot push the page sideways.\n\nLAYOUT ONLY. It has no role and adds none; pass `as` for the element that\nmeans something. It renders on a server.",
"import": "import { Grid } from 'ionbase-ui';",
"status": "stable",
"summary": "Columns that line up across rows, with gaps from the spacing scale. Reach for it before writing grid CSS: cards and tiles, a main column beside its aside, a form in two columns.",
"useWhen": [
"things that should line up in columns across rows — cards, tiles, a set of settings",
"a main column beside a narrower aside that falls under it on a smaller screen",
"a form's short fields side by side, one above the other on a phone"
],
"useInstead": [
{
"when": "things one after another in a single column or along a single line",
"use": "Stack",
"why": "a Stack has no columns to keep in line, and a row of controls sizes each to its content"
},
{
"when": "a set of numbers with their labels at the top of a dashboard",
"use": "StatGroup",
"why": "it lays its tiles out and names the group for a screen reader"
},
{
"when": "a label beside its value, row after row",
"use": "DescriptionList",
"why": "it is a `dl`: a screen reader hears each term with its value"
}
],
"composition": {
"order": [
"Grid"
],
"note": "`columns` is a count of equal columns (`3`) or each column's share of the row (`[2, 1]`: a main column twice its aside); it defaults to 2. Fixed columns fall to one at `collapse`: `mobile` (767px and below, the default), `tablet` (1023px and below — for a main column and its aside), or `never` (a pair that fits a phone, like two short numbers). `minColumnWidth` (160–360) instead fills each row with as many equal columns as fit, so a set of cards needs no breakpoint at all. `gap` is a step of the spacing scale, 16 by default; `rowGap` sets the rows apart when they need more. Cells in a row stretch to the tallest by default, so cards line up at the bottom too; `align=\"start\"` lets each keep its height. Pass `as=\"ul\"` for a list of cards and give each an `li`. Every column is `minmax(0, …)`, so a wide child — a table, a long ID — scrolls inside its cell rather than widening the page.",
"example": "\n …\n …\n\n\n\n {agents.map((a) => …)}\n"
},
"variants": {
"collapse": {
"mobile": {
"use": "the default — columns that read fine on a tablet: a form's fields in two columns, three small cards"
},
"tablet": {
"use": "a main column and its aside, or columns that need a desktop's width to hold what is in them"
},
"never": {
"use": "columns narrow enough for a phone — two short numbers, a pair of small toggles"
}
}
},
"slots": {
"children": {
"accepts": "any",
"note": "one cell each, in reading order across then down; `li` children when `as` is `ul` or `ol`"
}
},
"a11y": {
"guarantees": [
"layout only: it adds no role, so the element given by `as` — or the children — carry the meaning",
"the visual order is the DOM order: cells are placed across then down, never moved by `order` or explicit placement",
"no column can push the page sideways: every track is `minmax(0, …)`, and a filling grid's minimum gives way to a screen narrower than it",
"`as=\"ul\"` stays a list to a screen reader while losing its bullets"
],
"requires": [
"`as` for a group that means something — a list of cards is a `ul` — rather than a div"
],
"notes": [
"It renders on a server. A gap off the spacing scale, a column count it does not offer and a minimum width off its steps are type errors, not styles."
]
},
"antiPatterns": [
{
"dont": "a hand-written `display: grid` with a pixel gap and its own media query",
"do": "Grid with `columns`, `collapse` and a `gap` step",
"why": "the gap drifts off the scale and the breakpoint off the tokens', and nothing catches either"
},
{
"dont": "fixed columns for a set of cards whose count varies",
"do": "`minColumnWidth`",
"why": "the columns then follow the space: three on a desktop, one on a phone, with no breakpoint to choose"
},
{
"dont": "`collapse=\"never\"` on columns that hold text or tables",
"why": "on a phone each column is a sliver; the words wrap one to a line and a table scrolls in a strip"
},
{
"dont": "a Grid with one column",
"do": "Stack",
"why": "a single column is a Stack; the Grid only adds a template nothing uses"
}
],
"stylesheet": "src/styles/grid.css",
"tokens": [
"--ion-grid-columns",
"--ion-grid-gap",
"--ion-grid-min",
"--ion-grid-row-gap",
"--spacing-0",
"--spacing-12",
"--spacing-16",
"--spacing-2",
"--spacing-20",
"--spacing-24",
"--spacing-32",
"--spacing-4",
"--spacing-40",
"--spacing-48",
"--spacing-6",
"--spacing-64",
"--spacing-8"
],
"props": {
"columns": {
"type": "GridColumnCount | readonly GridFraction[] | undefined",
"required": false,
"origin": "own",
"description": "The columns: a count of equal ones (`3`), or each column's share\n(`[2, 1]` — a main column twice its aside). Ignored when\n`minColumnWidth` is set. Defaults to 2."
},
"minColumnWidth": {
"type": "GridMinColumnWidth | undefined",
"required": false,
"origin": "own",
"description": "Fill each row with as many columns as fit at this width or more, each\nthe same width. The count follows the space, so it needs no `collapse`."
},
"collapse": {
"type": "GridCollapse | undefined",
"required": false,
"origin": "own",
"description": "Where fixed columns fall to one. Defaults to `mobile`.",
"values": [
"tablet",
"mobile",
"never"
]
},
"gap": {
"type": "StackGap | undefined",
"required": false,
"origin": "own",
"description": "Space between the columns and the rows, from the spacing scale. Defaults to 16."
},
"rowGap": {
"type": "StackGap | undefined",
"required": false,
"origin": "own",
"description": "Space between the rows alone, when it differs from `gap`."
},
"align": {
"type": "GridAlign | undefined",
"required": false,
"origin": "own",
"description": "How a cell sits in its row. `stretch`, the default, makes every card in a\nrow the same height; `start` lets each keep its own.",
"values": [
"start",
"center",
"end",
"stretch"
]
},
"as": {
"type": "StackElement | undefined",
"required": false,
"origin": "own",
"description": "The element — a `ul` for a list of cards. Grid is layout only.",
"values": [
"form",
"div",
"span",
"section",
"nav",
"ul",
"ol",
"li",
"header",
"footer",
"fieldset"
]
},
"children": {
"type": "React.ReactNode",
"required": false,
"origin": "own"
}
},
"propCounts": {
"own": 8,
"aria": 0,
"dom": 277,
"other": 0
}
}