| 1 | ---
|
| 2 | title: Columns
|
| 3 | storybookPath: page-layout-columns--default
|
| 4 | isExperimentalPackage: false
|
| 5 | ---
|
| 6 |
|
| 7 | Use the columns primitive to layout content in configurable columns.
|
| 8 |
|
| 9 | Each child represents a single column. By default that column will span 1
|
| 10 | fraction of the total number of children.
|
| 11 |
|
| 12 | ```jsx live
|
| 13 | <Columns>
|
| 14 | <Placeholder />
|
| 15 | <Placeholder />
|
| 16 | <Placeholder />
|
| 17 | </Columns>
|
| 18 | ```
|
| 19 |
|
| 20 | ## Examples
|
| 21 |
|
| 22 | ### Gap
|
| 23 |
|
| 24 | The spacing between children can be adjusted using the `gap` prop.
|
| 25 |
|
| 26 | ```jsx live
|
| 27 | <Columns gap="large">
|
| 28 | <Placeholder />
|
| 29 | <Placeholder />
|
| 30 | <Placeholder />
|
| 31 | </Columns>
|
| 32 | ```
|
| 33 |
|
| 34 | ### Vertical alignment
|
| 35 |
|
| 36 | Columns can be aligned vertically using the `alignY` prop.
|
| 37 |
|
| 38 | ```jsx live
|
| 39 | <Stack gap="medium" dividers>
|
| 40 | <Columns gap="small" alignY="top">
|
| 41 | <Placeholder />
|
| 42 | <Placeholder label="top (default)" height={64} />
|
| 43 | <Placeholder />
|
| 44 | </Columns>
|
| 45 | <Columns gap="small" alignY="center">
|
| 46 | <Placeholder />
|
| 47 | <Placeholder label="center" height={64} />
|
| 48 | <Placeholder />
|
| 49 | </Columns>
|
| 50 | <Columns gap="small" alignY="bottom">
|
| 51 | <Placeholder />
|
| 52 | <Placeholder label="bottom" height={64} />
|
| 53 | <Placeholder />
|
| 54 | </Columns>
|
| 55 | <Columns gap="small" alignY="stretch">
|
| 56 | <Placeholder />
|
| 57 | <Placeholder label="stretch" height={64} />
|
| 58 | <Placeholder />
|
| 59 | </Columns>
|
| 60 | </Stack>
|
| 61 | ```
|
| 62 |
|
| 63 | ### Collapsing across breakpoints
|
| 64 |
|
| 65 | Columns can be collapsed into a single vertical stack responsively using the
|
| 66 | `collapseBelow` prop.
|
| 67 |
|
| 68 | ```jsx live
|
| 69 | <Columns gap="large" collapseBelow="desktop">
|
| 70 | <Placeholder />
|
| 71 | <Placeholder />
|
| 72 | <Placeholder />
|
| 73 | </Columns>
|
| 74 | ```
|
| 75 |
|
| 76 | ### Template
|
| 77 |
|
| 78 | If you need more control over how your columns are distributed, you can use the
|
| 79 | `template` prop. `template` receives an array of numbers that represent the
|
| 80 | relative width of each column.
|
| 81 |
|
| 82 | ```jsx live
|
| 83 | <Columns gap="small" template={[1, 3, 1]} collapseBelow="tablet">
|
| 84 | <Box border="field" padding="small">
|
| 85 | <Text>nav</Text>
|
| 86 | </Box>
|
| 87 | <Box border="field" padding="small">
|
| 88 | <Text>main</Text>
|
| 89 | </Box>
|
| 90 | <Box border="field" padding="small">
|
| 91 | <Text>aside</Text>
|
| 92 | </Box>
|
| 93 | </Columns>
|
| 94 | ```
|
| 95 |
|
| 96 | ## Props
|
| 97 |
|
| 98 | <PropsTable displayName="Columns" />
|
| 99 |
|
| 100 | [`Box`](/package/box) props are also included as `Column` props and are not
|
| 101 | listed here (excluding `display`, `alignItems`, `gap`, `flexDirection`,
|
| 102 | `justifyContent` and `flexWrap`).
|
| 103 |
|
| 104 | Extra props are passed into the underlying [`Box`](/package/box) component.
|
| 105 |
|
| 106 | [responsive-prop]:
|
| 107 | https://github.com/brighte-labs/spark-web/blob/e503bea4f7668d187ec7a78f99c5ed374417588b/packages/theme/src/themeUtils.ts#L11
|
| 108 | [responsive-range-props]:
|
| 109 | https://github.com/brighte-labs/spark-web/blob/e503bea4f7668d187ec7a78f99c5ed374417588b/packages/theme/src/themeUtils.ts#L130
|
| 110 | [gap]:
|
| 111 | https://github.com/brighte-labs/spark-web/blob/e7f6f4285b4cfd876312cc89fbdd094039aa239a/packages/columns/src/Columns.tsx#L17
|
| 112 | [data-attribute-map]:
|
| 113 | https://github.com/brighte-labs/spark-web/blob/e7f6f4285b4cfd876312cc89fbdd094039aa239a/packages/utils/src/internal/buildDataAttributes.ts#L1
|