## Feature Examples

### Aspect ratio
- description: Set the ratio with `aspectRatio` prop as a number of width divided by height, for example `16 / 9`. The default is `1`, a square. `<Proportion/>` takes the full width of its parent and calculates its height from the ratio. The child is stretched to fill the resulting area.
- example:
```jsx
<StorybookComponents.Stack alignItems="flex-start">
  <Box width="200px">
    <Proportion aspectRatio={1}>
      <Box
        height="100%"
        align="center"
        verticalAlign="middle"
        backgroundColor="B40"
      >
        <Text size="small">1</Text>
      </Box>
    </Proportion>
  </Box>
  <Box width="200px">
    <Proportion aspectRatio={4 / 3}>
      <Box
        height="100%"
        align="center"
        verticalAlign="middle"
        backgroundColor="B40"
      >
        <Text size="small">4 / 3</Text>
      </Box>
    </Proportion>
  </Box>
  <Box width="200px">
    <Proportion aspectRatio={16 / 9}>
      <Box
        height="100%"
        align="center"
        verticalAlign="middle"
        backgroundColor="B40"
      >
        <Text size="small">16 / 9</Text>
      </Box>
    </Proportion>
  </Box>
  <Box width="200px">
    <Proportion aspectRatio={2.5}>
      <Box
        height="100%"
        align="center"
        verticalAlign="middle"
        backgroundColor="B40"
      >
        <Text size="small">2.5</Text>
      </Box>
    </Proportion>
  </Box>
</StorybookComponents.Stack>;
```

### Predefined ratios
- description: Common ratios are available as `Proportion.PREDEFINED_RATIOS`: - `square` is 1:1, the default. - `portrait` is 3:4. - `landscape` is 4:3. - `cinema` is 16:9. - `none` disables the ratio.
- example:
```jsx
<StorybookComponents.Stack alignItems="flex-start">
  <Box width="160px">
    <Proportion aspectRatio={Proportion.PREDEFINED_RATIOS.square}>
      <Box
        height="100%"
        align="center"
        verticalAlign="middle"
        backgroundColor="B40"
      >
        <Text size="small">square</Text>
      </Box>
    </Proportion>
  </Box>
  <Box width="160px">
    <Proportion aspectRatio={Proportion.PREDEFINED_RATIOS.portrait}>
      <Box
        height="100%"
        align="center"
        verticalAlign="middle"
        backgroundColor="B40"
      >
        <Text size="small">portrait</Text>
      </Box>
    </Proportion>
  </Box>
  <Box width="160px">
    <Proportion aspectRatio={Proportion.PREDEFINED_RATIOS.landscape}>
      <Box
        height="100%"
        align="center"
        verticalAlign="middle"
        backgroundColor="B40"
      >
        <Text size="small">landscape</Text>
      </Box>
    </Proportion>
  </Box>
  <Box width="160px">
    <Proportion aspectRatio={Proportion.PREDEFINED_RATIOS.cinema}>
      <Box
        height="100%"
        align="center"
        verticalAlign="middle"
        backgroundColor="B40"
      >
        <Text size="small">cinema</Text>
      </Box>
    </Proportion>
  </Box>
</StorybookComponents.Stack>;
```

### No ratio
- description: Pass `aspectRatio="none"` to render the child at its natural size. Use it to switch the ratio off conditionally, for example when the content defines its own height.
- example:
```jsx
<StorybookComponents.Stack alignItems="flex-start">
  <Box width="240px">
    <Proportion>
      <Box padding="24px" backgroundColor="B40">
        <Text size="small">Square ratio</Text>
      </Box>
    </Proportion>
  </Box>
  <Box width="240px">
    <Proportion aspectRatio="none">
      <Box padding="24px" backgroundColor="B40">
        <Text size="small">Natural height</Text>
      </Box>
    </Proportion>
  </Box>
</StorybookComponents.Stack>;
```

### Container width
- description: The height follows the width of the container, so the same ratio gives a different size in every column and the tiles keep their shape when the layout resizes.
- example:
```jsx
<Layout>
  <Cell span={2}>
    <Proportion aspectRatio={4 / 3}>
      <Box
        height="100%"
        align="center"
        verticalAlign="middle"
        backgroundColor="B40"
      >
        <Text size="small">4:3</Text>
      </Box>
    </Proportion>
  </Cell>
  <Cell span={4}>
    <Proportion aspectRatio={4 / 3}>
      <Box
        height="100%"
        align="center"
        verticalAlign="middle"
        backgroundColor="B40"
      >
        <Text size="small">4:3</Text>
      </Box>
    </Proportion>
  </Cell>
  <Cell span={6}>
    <Proportion aspectRatio={4 / 3}>
      <Box
        height="100%"
        align="center"
        verticalAlign="middle"
        backgroundColor="B40"
      >
        <Text size="small">4:3</Text>
      </Box>
    </Proportion>
  </Cell>
</Layout>;
```

## Common Use Case Examples

### Media gallery
- description: Wrap every tile of a gallery in `<Proportion/>` so uploaded images of any dimensions and the `<AddItem/>` tile share the same square shape.
- example:
```jsx
<Layout>
  <Cell span={8}>
    <Card>
      <Card.Header
        title="Product Images"
        subtitle="Add up to 10 images. They’re cropped to a square in the gallery."
      />
      <Card.Divider />
      <Card.Content>
        <Layout>
          <Cell span={3}>
            <Proportion>
              <Image src="FoodExample1.jpg" height="100%" />
            </Proportion>
          </Cell>
          <Cell span={3}>
            <Proportion>
              <Image src="FoodExample2.jpg" height="100%" />
            </Proportion>
          </Cell>
          <Cell span={3}>
            <Proportion>
              <Image src="FoodExample3.jpg" height="100%" />
            </Proportion>
          </Cell>
          <Cell span={3}>
            <Proportion>
              <AddItem size="small">Add Image</AddItem>
            </Proportion>
          </Cell>
        </Layout>
      </Card.Content>
    </Card>
  </Cell>
</Layout>;
```