# Auto Grid
> A grid layout that is responsive based on the size of its container and given constraints.

## Import

```js
import { AutoGrid } from '@gemini-suite/vera-react';
```

## Background

**Auto Grid** creates responsive layout with automatically-placed and flexible children.
It is responsive based on the size of its container and provided `min` (and optionally `max`) value. By setting these constraints, you empower the browser to make the right decision about the layout given the available space. Each column will resize at the same rate, and items will begin to break to a new row if the width reaches the `min` value.

**Auto Grid** fits into any container and reconfigures automatically thanks to CSS grid’s `auto-fit()` and `minmax()` functions, without any need for viewport `@media` queries.
With **Auto Grid** you're encouraged to think about the content first (it's minimum and maximum size), not the viewport or the device size.

## Examples

### Default configuration

```jsx resizable=true
<AutoGrid>
  <ExampleBox />
  <ExampleBox />
  <ExampleBox />
  <ExampleBox />
  <ExampleBox />
  <ExampleBox />
</AutoGrid>
```

### Narrow container

```jsx
<Box css={{ maxWidth: '10rem', mx: 'auto' }}>
  <AutoGrid>
    <ExampleBox />
    <ExampleBox />
    <ExampleBox />
    <ExampleBox />
    <ExampleBox />
  </AutoGrid>
</Box>
```

### Configuring min

In the example below it is specified that each grid item must be of a minimum size of `6rem`.
**AutoGrid** will squeeze in as many equal width (greater than `6rem`), flexible sized grid items as it can to fit inside.

```jsx resizable=true
<AutoGrid min="6rem">
  {Array(24)
    .fill()
    .map((_, i) => (
      <ExampleBox key={i} />
    ))}
</AutoGrid>
```

### Configuring max

Optional `max` property gives you a bit more control over the automatic distribution of columns.
Say you want two columns at larger screen sizes, nothing more, while keeping the minimum size of `6rem`. The grid items will grow to reach the maximum size when there is enough space.

```jsx resizable=true
<AutoGrid min="6rem" max="50%">
  {Array(6)
    .fill()
    .map((_, i) => (
      <ExampleBox key={i} />
    ))}
</AutoGrid>
```

If you need at most 3 columns, you can set `max` to `33.3333%` or provide a simple math expression `calc(100% / 3)`.

```jsx resizable=true
<AutoGrid min="12rem" max="calc(100% / 3)">
  {Array(6)
    .fill()
    .map((_, i) => (
      <ExampleBox key={i} />
    ))}
</AutoGrid>
```

### Alignment

#### alignItems="center"

```jsx resizable=true
<AutoGrid
  alignItems="center"
  css={{
    backgroundColor: '$colorBlue10'
  }}
>
  <ExampleBox css={{ height: '6rem' }} />
  <ExampleBox />
  <ExampleBox />
  <ExampleBox css={{ height: '6rem' }} />
</AutoGrid>
```

#### alignItems="end"

```jsx resizable=true
<AutoGrid min="12rem" alignItems="end">
  <Box css={{ backgroundColor: '$colorBlue10' }}>
    <Flex flow="column" gap="none">
      <AspectRatio ratio={2 / 1}>
        <img
          src="https://images.unsplash.com/photo-1535025183041-0991a977e25b?w=300&dpr=2&q=80"
          alt="Landscape photo by Tobias Tullius"
        />
      </AspectRatio>
      <FakeText words="10,15" css={{ p: '$spacingM' }} />
    </Flex>
  </Box>
  <Box css={{ backgroundColor: '$colorBlue10' }}>
    <Flex flow="column" gap="none">
      <AspectRatio ratio={2 / 1}>
        <img
          src="https://images.unsplash.com/photo-1539593395743-7da5ee10ff07?w=300&dpr=2&q=80"
          alt=""
        />
      </AspectRatio>
      <FakeText words="20,25" css={{ p: '$spacingM' }} />
    </Flex>
  </Box>
  <Box css={{ backgroundColor: '$colorBlue10' }}>
    <Flex flow="column" gap="none">
      <AspectRatio ratio={2 / 1}>
        <img
          src="https://images.unsplash.com/photo-1433477155337-9aea4e790195?w=300&dpr=2&q=80"
          alt=""
        />
      </AspectRatio>
      <FakeText words="10,15" css={{ p: '$spacingM' }} />
    </Flex>
  </Box>
</AutoGrid>
```

---

## API Reference

| Name         | Type                                                      | Default      | Description                                                                                                                                                                                                                                                                                  | Required |
| ------------ | --------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`         | `keyof JSX.IntrinsicElements \| React.ComponentType<any>` | `div`        | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   For more details, read our [Composition](/get-started/composition#polymorphism) guide. |          |
| `css`        | `StitchesCss`                                             |              | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants.                                                 |          |
| `min`        | `StitchesCss['width']`                                    | `250px`      | The minimum size if each grid item. A CSS length value representing `x` in `minmax(min(100%, max(0px, x)), 1fr)`.                                                                                                                                                                            |          |
| `max`        | `StitchesCss['width']`                                    | `0px`        | The maximum size if each grid item. A CSS length value representing `x` in `minmax(min(100%, max(x, 250px)), 1fr)`.                                                                                                                                                                          |          |
| `alignItems` | `"start" \| "center" \| "end" \| "baseline" \| "stretch"` |              | Defines the alignment of the items inside the grid container on the block (column) axis.                                                                                                                                                                                                     |          |
| `gap`        | `SpacingToken`                                            | `"spacingM"` | Spacing between grid items.                                                                                                                                                                                                                                                                  |          |