# React Native Layout (Box, Grid, Container, Center, Spacer, AspectRatio)

> React Native layout components for iOS, Android and the web: Box with theme spacing, colors, corners and shadows as props, a responsive Grid, a max-width Container, Center, Spacer and AspectRatio. No dependencies.

# Layout

Six small building blocks for screens, all reading the theme: `Box` for a styled view, `Grid` for columns, `Container` for a readable width, `Center`, `Spacer` and `AspectRatio`. For rows and columns with a gap, use [Stack](./stack).

```tsx
import { AspectRatio, Box, Center, Container, Grid, Spacer } from 'patine-ui';
```

```tsx live
import { AspectRatio, Badge, Box, Grid, HStack, Spacer, Text, View } from 'patine-ui';

const PLACES = [
  { name: 'Lisbon', price: '$142', color: '#F59E0B' },
  { name: 'Kyoto', price: '$210', color: '#EF4444' },
  { name: 'Reykjavík', price: '$188', color: '#0EA5E9' },
  { name: 'Oaxaca', price: '$96', color: '#10B981' },
];

export default function Example() {
  return (
    <Box padding="lg" background="surface" radius="lg" gap="md">
      <HStack>
        <Text weight="semibold" size="lg">Stays this weekend</Text>
        <Spacer />
        <Badge variant="secondary">4 places</Badge>
      </HStack>
      <Grid minColumnWidth={140} gap="md">
        {PLACES.map((place) => (
          <Box key={place.name} background="background" radius="md" shadow="xs" style={{ overflow: 'hidden' }}>
            <AspectRatio ratio={4 / 3}>
              <View style={{ flex: 1, backgroundColor: place.color }} />
            </AspectRatio>
            <Box padding="sm" row justify="space-between">
              <Text weight="medium">{place.name}</Text>
              <Text color="textSecondary">{place.price}</Text>
            </Box>
          </Box>
        ))}
      </Grid>
    </Box>
  );
}
```

## Example: an account dashboard

A web app's account home, laid out with the layout parts alone: a `Container` keeps it readable on a wide screen, a `Grid` fits as many cards as the width allows, and `Spacer` pushes each card's action to its edge.

```tsx live wide
import { Badge, Box, Button, Container, Grid, HStack, Spacer, Text, VStack } from 'patine-ui';

const CARDS = [
  { title: 'Plan', value: 'Team · 8 seats', action: 'Manage', badge: 'Renews Dec 3' },
  { title: 'Usage', value: '62% of storage', action: 'Details' },
  { title: 'Invoices', value: 'Last: €392.00', action: 'Download' },
  { title: 'Security', value: 'Two-step on', action: 'Review', badge: '1 new device' },
];

export default function Example() {
  return (
    <Container size="md">
      <VStack gap="md">
        <HStack>
          <VStack>
            <Text size="lg" weight="semibold">Juniper & Co.</Text>
            <Text color="textSecondary">maya@juniper.co</Text>
          </VStack>
          <Spacer />
          <Button size="sm" variant="outline">Edit profile</Button>
        </HStack>
        <Grid minColumnWidth={200} gap="md">
          {CARDS.map((card) => (
            <Box key={card.title} border radius="lg" padding="md" gap="sm">
              <HStack>
                <Text weight="medium">{card.title}</Text>
                <Spacer />
                {card.badge ? <Badge variant="secondary">{card.badge}</Badge> : null}
              </HStack>
              <Text color="textSecondary">{card.value}</Text>
              <HStack>
                <Spacer />
                <Button size="sm" variant="ghost">{card.action}</Button>
              </HStack>
            </Box>
          ))}
        </Grid>
      </VStack>
    </Container>
  );
}
```

## Box

A `View` with the theme as props: `padding`, `paddingX`, `paddingY`, `margin`, `gap`, `background` (a theme color), `radius`, `border`, `shadow`, `row`, `align`, `justify` and `flex`. Its own `style` still wins.

```tsx live
import { Box, Text } from 'patine-ui';

export default function Example() {
  return (
    <Box padding="lg" background="primaryMuted" radius="md" border gap="xs">
      <Text weight="semibold" color="primary">Free shipping</Text>
      <Text color="textSecondary">On orders over $50, this week only.</Text>
    </Box>
  );
}
```

## Grid

Equal columns that wrap into rows. Give it a fixed `columns`, or a `minColumnWidth` and it fits as many columns as it can, re-flowing when the window or the device turns. `gap` sets both gaps; `rowGap` and `columnGap` set one.

## Container

Keeps content to a readable width, centered, with `padding` at the sides. It's full width on a phone and a column on a desktop: `size` is `'sm'` (640), `'md'` (768), `'lg'` (1024, the default), `'xl'` (1280) or `'full'`.

```tsx live
import { Container, Text } from 'patine-ui';

export default function Example() {
  return (
    <Container size="sm" style={{ backgroundColor: 'rgba(99,102,241,0.08)', paddingVertical: 16 }}>
      <Text>This paragraph never grows wider than 640 points, however wide the window.</Text>
    </Container>
  );
}
```

## Center, Spacer and AspectRatio

`Center` puts its children in the middle; `fill` stretches it over its parent first. `Spacer` grows to push its neighbours apart, or takes a fixed `size`. `AspectRatio` keeps a `ratio` as it resizes, and its children fill it.

```tsx live
import { AspectRatio, Avatar, Button, Center, HStack, Spacer, Text } from 'patine-ui';

export default function Example() {
  return (
    <>
      <HStack style={{ marginBottom: 16 }}>
        <Avatar name="Maya Cohen" size="sm" />
        <Spacer size="sm" />
        <Text weight="medium">Maya Cohen</Text>
        <Spacer />
        <Button size="sm" variant="outline">Follow</Button>
      </HStack>
      <AspectRatio ratio={16 / 9} style={{ borderRadius: 12, backgroundColor: '#111827' }}>
        <Center fill>
          <Text style={{ color: 'white' }}>16 : 9 video</Text>
        </Center>
      </AspectRatio>
    </>
  );
}
```

## Accessibility

These are layout only, with no role of their own. `Spacer` is hidden from screen readers.

## Props

All of them also take `View` props. Spacing takes a step of the theme's scale (`'xs'`–`'xl'`) or a number of points.

### Box

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `padding`, `paddingX`, `paddingY` | `Space` | — | Space inside. |
| `margin`, `marginX`, `marginY` | `Space` | — | Space outside. |
| `gap` | `Space` | — | Space between children. |
| `background` | `keyof Theme['colors']` | — | A theme color for the fill, e.g. `'surface'`. |
| `radius` | `'sm' \| 'md' \| 'lg' \| 'full' \| 'sheet'` | — | A theme corner radius. |
| `border` | `boolean` | `false` | A hairline in the theme's border color. |
| `shadow` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | — | A step of the theme's elevation. |
| `row` | `boolean` | `false` | Lay children in a row. |
| `align`, `justify`, `flex` | `ViewStyle` values | — | Flex layout. |
| `theme` | `DeepPartial<Theme>` | — | Theme override. |
| `ref` | `Ref<View>` | — | The underlying view, e.g. to `measure()` it. |

### Grid

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `number` | `2` | A fixed number of equal columns. |
| `minColumnWidth` | `number` | — | As many columns as fit at least this wide. Wins over `columns`. |
| `gap` | `Space` | `'md'` | Space between cells, both ways. |
| `rowGap`, `columnGap` | `Space` | `gap` | Space between rows, or columns. |

### Container

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'lg'` | Its widest: 640, 768, 1024, 1280 or none. |
| `padding` | `Space` | `'lg'` | Space at the sides. |

### Center, Spacer, AspectRatio

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `fill` (Center) | `boolean` | `false` | Fill the parent first. |
| `size` (Spacer) | `Space` | — | A fixed space. Without it, it grows. |
| `ratio` (AspectRatio) | `number` | `1` | Width over height, e.g. `16 / 9`. |
| `width` (AspectRatio) | `DimensionValue` | `'100%'` | Its width; the height follows. |
