# Grid

> Responsive equal-width column layouts. Grid2 through Grid6 render two to six columns that reduce on smaller screens; they share one API and differ only in column count.

Source: https://vaneui.com/docs/layout-components/grid

Import: `import { Grid2, Grid3, Grid4, Grid5, Grid6, Card, Col, Text, ThemeProvider, Title } from "@vaneui/ui"`

Use a Grid component when cards or tiles should line up in columns. Each one renders a `<div>` with CSS grid display, so the cells in a row all get the same width whatever their content. For flex items that keep their content width, use [Row](/docs/layout-components/row); for data compared across rows and columns, use [Table](/docs/layout-components/table).

## Basic usage

The Grid family renders equal-width column layouts: `Grid2` through `Grid6` for two to six columns. Children flow left to right and wrap to the next row. `md`, `gap`, `noPadding`, `outline`, and `sharp` are defaults, so none of them need to be specified.

```tsx demo
<Grid3>
  <Card>
    <Title>Item 1</Title>
    <Text>Three-column layout</Text>
  </Card>
  <Card>
    <Title>Item 2</Title>
    <Text>Equal widths</Text>
  </Card>
  <Card>
    <Title>Item 3</Title>
    <Text>Wraps to next row</Text>
  </Card>
</Grid3>
```

## Column counts

Pick the component for the number of columns you need, from `Grid2` to `Grid6`. They share the same API and differ only in the column count.

```tsx demo
<Col>
  <Text fontSemibold>Grid2</Text>
  <Grid2>
    <Card><Text textCenter>1</Text></Card>
    <Card><Text textCenter>2</Text></Card>
  </Grid2>
  <Text fontSemibold>Grid3</Text>
  <Grid3>
    <Card><Text textCenter>1</Text></Card>
    <Card><Text textCenter>2</Text></Card>
    <Card><Text textCenter>3</Text></Card>
  </Grid3>
  <Text fontSemibold>Grid4</Text>
  <Grid4>
    <Card><Text textCenter>1</Text></Card>
    <Card><Text textCenter>2</Text></Card>
    <Card><Text textCenter>3</Text></Card>
    <Card><Text textCenter>4</Text></Card>
  </Grid4>
  <Text fontSemibold>Grid6</Text>
  <Grid6>
    <Card><Text textCenter>1</Text></Card>
    <Card><Text textCenter>2</Text></Card>
    <Card><Text textCenter>3</Text></Card>
    <Card><Text textCenter>4</Text></Card>
    <Card><Text textCenter>5</Text></Card>
    <Card><Text textCenter>6</Text></Card>
  </Grid6>
</Col>
```

## Responsive columns

Each grid reduces its column count on smaller screens so cells never get too narrow. The breakpoints are tablet (below 1024px) and mobile (below 768px). Resize the window to see the reflow.

| Component | Desktop | Tablet | Mobile |
|-----------|---------|--------|--------|
| `Grid2`   | 2       | 2      | 1      |
| `Grid3`   | 3       | 2      | 1      |
| `Grid4`   | 4       | 3      | 2      |
| `Grid5`   | 5       | 3      | 2      |
| `Grid6`   | 6       | 4      | 2      |

## Sizes

Sizes (`xs`, `sm`, `md`, `lg`, `xl`) scale the grid's `gap` and `border-radius`.

```tsx demo
<Col>
  <Text fontSemibold>xs</Text>
  <Grid3 xs>
    <Card xs><Text xs>Item 1</Text></Card>
    <Card xs><Text xs>Item 2</Text></Card>
    <Card xs><Text xs>Item 3</Text></Card>
  </Grid3>
  <Text fontSemibold>sm</Text>
  <Grid3 sm>
    <Card sm><Text sm>Item 1</Text></Card>
    <Card sm><Text sm>Item 2</Text></Card>
    <Card sm><Text sm>Item 3</Text></Card>
  </Grid3>
  <Text fontSemibold>md (default)</Text>
  <Grid3>
    <Card><Text>Item 1</Text></Card>
    <Card><Text>Item 2</Text></Card>
    <Card><Text>Item 3</Text></Card>
  </Grid3>
  <Text fontSemibold>lg</Text>
  <Grid3 lg>
    <Card lg><Text lg>Item 1</Text></Card>
    <Card lg><Text lg>Item 2</Text></Card>
    <Card lg><Text lg>Item 3</Text></Card>
  </Grid3>
  <Text fontSemibold>xl</Text>
  <Grid3 xl>
    <Card xl><Text xl>Item 1</Text></Card>
    <Card xl><Text xl>Item 2</Text></Card>
    <Card xl><Text xl>Item 3</Text></Card>
  </Grid3>
</Col>
```

## Appearances

Grid supports color appearances. Pair with `filled` or `border` to make the surface visible.

```tsx demo
<Col>
  <Grid3 filled primary>
    <Card><Text>Item 1</Text></Card>
    <Card><Text>Item 2</Text></Card>
    <Card><Text>Item 3</Text></Card>
  </Grid3>
  <Grid3 filled success>
    <Card><Text>Item 1</Text></Card>
    <Card><Text>Item 2</Text></Card>
    <Card><Text>Item 3</Text></Card>
  </Grid3>
</Col>
```

## Variants

`outline` is the default. Use `filled` for a solid background, or add `border` for a visible outline.

```tsx demo
<Col>
  <Grid3 filled primary>
    <Card><Text>Filled primary</Text></Card>
    <Card><Text>Item 2</Text></Card>
    <Card><Text>Item 3</Text></Card>
  </Grid3>
  <Grid3 border success>
    <Card><Text>Outline success</Text></Card>
    <Card><Text>Item 2</Text></Card>
    <Card><Text>Item 3</Text></Card>
  </Grid3>
</Col>
```

## Shapes

`sharp` is the default. Use `rounded` for soft corners or `pill` for fully rounded edges. Shape applies to the grid container itself, so pair with `filled` or `border` to see it.

```tsx demo
<Col>
  <Grid3 filled secondary sharp padding>
    <Card><Text>Sharp (default)</Text></Card>
    <Card><Text>Item 2</Text></Card>
    <Card><Text>Item 3</Text></Card>
  </Grid3>
  <Grid3 filled secondary rounded padding>
    <Card><Text>Rounded</Text></Card>
    <Card><Text>Item 2</Text></Card>
    <Card><Text>Item 3</Text></Card>
  </Grid3>
</Col>
```

## With gap

`gap` is on by default. Use `noGap` to remove spacing between cells.

```tsx demo
<Col>
  <Text fontSemibold>Default gap</Text>
  <Grid3>
    <Card><Text>Item 1</Text></Card>
    <Card><Text>Item 2</Text></Card>
    <Card><Text>Item 3</Text></Card>
  </Grid3>
  <Text fontSemibold>noGap</Text>
  <Grid3 noGap>
    <Card sharp><Text>Item 1</Text></Card>
    <Card sharp><Text>Item 2</Text></Card>
    <Card sharp><Text>Item 3</Text></Card>
  </Grid3>
</Col>
```

## Customizing

Set app-wide Grid defaults with `ThemeProvider`'s `themeDefaults`. Each column count has its own key (`grid2` through `grid6`).

```tsx demo
<ThemeProvider themeDefaults={{
  grid3: { lg: true },
}}>
  <Grid3>
    <Card><Text>Item 1</Text></Card>
    <Card><Text>Item 2</Text></Card>
    <Card><Text>Item 3</Text></Card>
  </Grid3>
</ThemeProvider>
```

## Props

| Prop | Category | Default | Description |
| --- | --- | --- | --- |
| `primary` | Appearance |  | Primary color appearance (gray) |
| `accent` | Appearance |  | Accent color appearance (rose) |
| `secondary` | Appearance |  | Secondary color appearance (gray) |
| `tertiary` | Appearance |  | Tertiary color appearance |
| `success` | Appearance |  | Success color appearance (green) |
| `danger` | Appearance |  | Danger color appearance (red) |
| `warning` | Appearance |  | Warning color appearance (amber) |
| `info` | Appearance |  | Info color appearance (cyan) |
| `inheritAppearance` | Appearance |  | Inherit appearance from parent — suppresses own data-appearance/data-variant, uses parent's CSS variables |
| `flex1` | Flex |  | Take up remaining space (= `flex-1`, i.e. `flex: 1 1 0%`) |
| `flexAuto` | Flex |  | Grow but respect intrinsic size (= `flex-auto`, i.e. `flex: 1 1 auto`) |
| `flexNone` | Flex |  | Don't grow and don't shrink (= `flex-none`, i.e. `flex: none`) |
| `margin` | Margin |  | Enable margin on all sides |
| `marginX` | Margin |  | Enable only horizontal (inline) margin |
| `marginY` | Margin |  | Enable only vertical (block) margin |
| `marginT` | Margin |  | Enable only top margin |
| `marginB` | Margin |  | Enable only bottom margin |
| `noMargin` | Margin |  | Disable margin (reset to 0) |
| `padding` | Padding |  | Enable internal padding |
| `paddingX` | Padding |  | Enable only horizontal padding |
| `paddingY` | Padding |  | Enable only vertical padding |
| `noPadding` | Padding | yes | Disable internal padding |
| `pill` | Shape |  | Fully rounded corners (circular) |
| `sharp` | Shape | yes | No rounded corners (square) |
| `rounded` | Shape |  | Medium rounded corners (default) |
| `noShrink` | Shrink |  | Prevent the flex item from shrinking below its content size (= `shrink-0`) |
| `xs` | Size |  | Extra small size |
| `sm` | Size |  | Small size |
| `md` | Size | yes | Medium size (default) |
| `lg` | Size |  | Large size |
| `xl` | Size |  | Extra large size |
| `filled` | Variant |  | Filled variant - solid background with contrasting text color |
| `outline` | Variant | yes | Outline variant - transparent background with border and colored text (default) |
| `ghost` | Variant |  | Ghost variant - transparent background, no border, appearance-colored text, tinted hover background |

Layout and utility props (Border, Display, Flex Direction, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Transparent, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).