# SymmetricGrid

> Molecule — orn-ui

> ⚠️ Requires <UIProvider>: This component (like every orn-ui component) must render inside a <UIProvider> ancestor, or it throws at runtime. See https://orn-ui-docs.vercel.app/getting-started.md

> Runs on Expo SDK 54, 55, 56 and 57, and on bare React Native >=0.81 with react >=19.1. No native modules — works in Expo Go, no prebuild.

## Installation

Install just this component (copies the source into your project, no npm dependency)
```bash
npx orn-ui add symmetric-grid
```

Or install the whole package and import it
```tsx
pnpm add orn-ui
import { SymmetricGrid } from 'orn-ui/symmetric-grid';
```

Depends on: core (theme + icons)

## Variants

### columns={2} — default, last row of 1 centered

```tsx
<SymmetricGrid
  data={ITEMS}
  columns={2}
  keyExtractor={(item) => item.id}
  renderItem={(item) => <Tile name={item.name} />}
/>
```

### columns={3} — same 5 items, different grid

```tsx
<SymmetricGrid
  data={ITEMS}
  columns={3}
  keyExtractor={(item) => item.id}
  renderItem={(item) => <Tile name={item.name} />}
/>
```

### balanceLastRow={false} — incomplete row left-aligned instead of centered

```tsx
<SymmetricGrid
  data={ITEMS}
  columns={2}
  balanceLastRow={false}
  keyExtractor={(item) => item.id}
  renderItem={(item) => <Tile name={item.name} />}
/>
```

## Full demo source

```tsx
const variants: VariantDef[] = [
  {
    label: 'columns={2} — default, last row of 1 centered',
    content: (
      <SymmetricGrid
        data={ITEMS}
        columns={2}
        keyExtractor={(item) => item.id}
        renderItem={(item) => <Tile name={item.name} />}
      />
    ),
  },
  {
    label: 'columns={3} — same 5 items, different grid',
    content: (
      <SymmetricGrid
        data={ITEMS}
        columns={3}
        keyExtractor={(item) => item.id}
        renderItem={(item) => <Tile name={item.name} />}
      />
    ),
  },
  {
    label: 'balanceLastRow={false} — incomplete row left-aligned instead of centered',
    content: (
      <SymmetricGrid
        data={ITEMS}
        columns={2}
        balanceLastRow={false}
        keyExtractor={(item) => item.id}
        renderItem={(item) => <Tile name={item.name} />}
      />
    ),
  },
];
return <VariantList variants={variants} />;
```

## Props

| Name | Type | Default | Description |
|---|---|---|---|
| `data` | `T[]` | — | — |
| `renderItem` | `(item: T, index: number) => ReactElement<unknown, string \| JSXElementConstructor<any>>` | — | — |
| `keyExtractor` | `(item: T, index: number) => string` | — | — |
| `columns?` | `number` | 2 | Columns per row. |
| `gap?` | `number` | theme.tokens.spacing.md | Spacing between cells, on both axes. |
| `balanceLastRow?` | `boolean` | true | Incomplete last row: centered (symmetric) instead of stuck to the left with a gap on the right. |
| `style?` | `StyleProp<ViewStyle>` | — | — |