0
# Layout Components
1

2
Core layout primitives that provide flexible, responsive interfaces with consistent spacing, alignment, and visual hierarchy. All layout components support responsive props and theme integration.
3

4
## Capabilities
5

6
### Box Component
7

8
The foundational layout component that provides comprehensive styling props including colors, spacing, borders, and layout controls. All other components in the library extend from Box.
9

10
```typescript { .api }
11
/**
12
 * Foundational layout component with comprehensive styling props
13
 * @param props - Box styling and content props
14
 * @returns JSX element with applied styles
15
 */
16
function Box(props: BoxProps): JSX.Element;
17

18
interface BoxProps extends ColorProps, RadiiProps, MarginProps, PaddingProps {
19
  /** Text alignment */
20
  textAlign?: ResponsiveProp<'left' | 'right' | 'center' | 'justify' | 'start' | 'end'>;
21
  /** Element height */
22
  height?: ResponsiveProp<string | number>;
23
  /** Element width */
24
  width?: ResponsiveProp<string | number>;
25
  /** Element or component to render as */
26
  as?: ElementType;
27
  /** Child elements */
28
  children?: ReactNode;
29
}
30

31
interface ColorProps {
32
  /** Background color from theme palette */
33
  background?: ResponsiveProp<keyof Theme['palette']>;
34
  /** Text color from theme palette */
35
  foreground?: ResponsiveProp<keyof Theme['palette']>;
36
}
37

38
interface RadiiProps {
39
  /** Border radius from theme radii */
40
  rounding?: ResponsiveProp<keyof Theme['radii']>;
41
  /** Bottom border radius */
42
  roundingBottom?: ResponsiveProp<keyof Theme['radii']>;
43
  /** Left border radius */  
44
  roundingLeft?: ResponsiveProp<keyof Theme['radii']>;
45
  /** Right border radius */
46
  roundingRight?: ResponsiveProp<keyof Theme['radii']>;
47
  /** Top border radius */
48
  roundingTop?: ResponsiveProp<keyof Theme['radii']>;
49
}
50

51
interface MarginProps {
52
  /** Margin on all sides */
53
  margin?: ResponsiveProp<keyof Theme['spacing']>;
54
  /** Top margin */
55
  marginTop?: ResponsiveProp<keyof Theme['spacing']>;
56
  /** Right margin */
57
  marginRight?: ResponsiveProp<keyof Theme['spacing']>;
58
  /** Bottom margin */
59
  marginBottom?: ResponsiveProp<keyof Theme['spacing']>;
60
  /** Left margin */
61
  marginLeft?: ResponsiveProp<keyof Theme['spacing']>;
62
  /** Vertical margin (top and bottom) */
63
  marginY?: ResponsiveProp<keyof Theme['spacing']>;
64
  /** Horizontal margin (left and right) */
65
  marginX?: ResponsiveProp<keyof Theme['spacing']>;
66
}
67

68
interface PaddingProps {
69
  /** Padding on all sides */
70
  padding?: ResponsiveProp<keyof Theme['spacing']>;
71
  /** Top padding */
72
  paddingTop?: ResponsiveProp<keyof Theme['spacing']>;
73
  /** Right padding */
74
  paddingRight?: ResponsiveProp<keyof Theme['spacing']>;
75
  /** Bottom padding */
76
  paddingBottom?: ResponsiveProp<keyof Theme['spacing']>;
77
  /** Left padding */
78
  paddingLeft?: ResponsiveProp<keyof Theme['spacing']>;
79
  /** Vertical padding (top and bottom) */
80
  paddingY?: ResponsiveProp<keyof Theme['spacing']>;
81
  /** Horizontal padding (left and right) */
82
  paddingX?: ResponsiveProp<keyof Theme['spacing']>;
83
}
84
```
85

86
**Usage Examples:**
87

88
```typescript
89
import { Box } from "@keystone-ui/core";
90

91
// Basic styled container
92
<Box 
93
  padding="large" 
94
  background="neutral100" 
95
  rounding="medium"
96
>
97
  Content here
98
</Box>
99

100
// Responsive styling
101
<Box 
102
  padding={["small", "medium", "large"]}
103
  background={["white", "neutral50"]}
104
  width={["100%", "50%"]}
105
>
106
  Responsive content
107
</Box>
108

109
// Polymorphic usage
110
<Box as="section" padding="xlarge">
111
  <Box as="header" marginBottom="large">
112
    Header content
113
  </Box>
114
</Box>
115
```
116

117
### Box Styles Hook
118

119
Hook for generating Box component styles programmatically.
120

121
```typescript { .api }
122
/**
123
 * Hook for generating Box component styles
124
 * @param props - Box styling props
125
 * @returns CSS styles object for use with Emotion
126
 */
127
function useBoxStyles(props: BoxProps): any;
128
```
129

130
### Stack Component
131

132
Flexible layout component for arranging children vertically or horizontally with consistent gaps and optional dividers.
133

134
```typescript { .api }
135
/**
136
 * Flexible layout component for vertical/horizontal arrangement
137
 * @param props - Stack layout and styling props
138
 * @returns JSX element with flexbox layout
139
 */
140
function Stack(props: StackProps): JSX.Element;
141

142
interface StackProps extends BoxProps {
143
  /** Alignment of items along the cross axis */
144
  align?: 'center' | 'end' | 'start' | 'stretch';
145
  /** Child elements to arrange */
146
  children: ReactNode;
147
  /** Arrange horizontally instead of vertically */
148
  across?: boolean;
149
  /** Divider placement between/around items */
150
  dividers?: 'none' | 'around' | 'between' | 'start' | 'end';
151
  /** Gap size between items from theme spacing */
152
  gap?: keyof Theme['spacing'];
153
}
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
import { Stack, Text } from "@keystone-ui/core";
160

161
// Vertical stack with gap
162
<Stack gap="medium">
163
  <Text>First item</Text>
164
  <Text>Second item</Text>
165
  <Text>Third item</Text>
166
</Stack>
167

168
// Horizontal stack with dividers
169
<Stack across gap="small" dividers="between" align="center">
170
  <Text>Nav item 1</Text>
171
  <Text>Nav item 2</Text>
172
  <Text>Nav item 3</Text>
173
</Stack>
174

175
// Stack with custom styling
176
<Stack 
177
  gap="large" 
178
  padding="xlarge" 
179
  background="neutral100"
180
  rounding="medium"
181
>
182
  <Text size="large" weight="bold">Title</Text>
183
  <Text>Description text</Text>
184
</Stack>
185
```
186

187
### Inline Component
188

189
Horizontal layout component that wraps items to new lines as needed, with consistent spacing.
190

191
```typescript { .api }
192
/**
193
 * Horizontal wrapping layout component
194
 * @param props - Inline layout and styling props  
195
 * @returns JSX element with flexbox wrap layout
196
 */
197
function Inline(props: InlineProps): JSX.Element;
198

199
interface InlineProps extends BoxProps {
200
  /** Alignment of items along the cross axis */
201
  align?: 'center' | 'end' | 'start' | 'stretch';
202
  /** Child elements to arrange */
203
  children: ReactNode;
204
  /** Gap size between items from theme spacing */
205
  gap?: keyof Theme['spacing'];
206
}
207
```
208

209
**Usage Examples:**
210

211
```typescript
212
import { Inline, Text } from "@keystone-ui/core";
213

214
// Tag-like inline layout
215
<Inline gap="small">
216
  <Text background="blue100" padding="xsmall" rounding="small">Tag 1</Text>
217
  <Text background="blue100" padding="xsmall" rounding="small">Tag 2</Text>
218
  <Text background="blue100" padding="xsmall" rounding="small">Tag 3</Text>
219
</Inline>
220

221
// Button group
222
<Inline gap="medium" align="center">
223
  <button>Save</button>
224
  <button>Cancel</button>
225
  <button>Delete</button>
226
</Inline>
227
```
228

229
### Center Component
230

231
Layout component for centering content both horizontally and vertically.
232

233
```typescript { .api }
234
/**
235
 * Component for centering content horizontally and vertically
236
 * @param props - Center layout and styling props
237
 * @returns JSX element with centered content
238
 */
239
function Center(props: CenterProps): JSX.Element;
240

241
interface CenterProps extends BoxProps {
242
  /** Fill entire viewport height and width */
243
  fillView?: boolean;
244
}
245
```
246

247
**Usage Examples:**
248

249
```typescript
250
import { Center, Text } from "@keystone-ui/core";
251

252
// Center content in container
253
<Center height="200px">
254
  <Text>Centered content</Text>
255
</Center>
256

257
// Full viewport centering
258
<Center fillView>
259
  <Text size="large">Loading...</Text>  
260
</Center>
261
```
262

263
### Divider Component
264

265
Visual separator component with horizontal or vertical orientation and theme-integrated styling.
266

267
```typescript { .api }
268
/**
269
 * Visual separator with orientation support
270
 * @param props - Divider styling and layout props
271
 * @returns JSX element as visual separator
272
 */
273
function Divider(props: DividerProps): JSX.Element;
274

275
interface DividerProps extends MarginProps {
276
  /** Divider color from theme palette */
277
  color?: ResponsiveProp<keyof Theme['palette']>;
278
  /** Divider orientation */
279
  orientation?: 'horizontal' | 'vertical';
280
  /** CSS class name */
281
  className?: string;
282
  /** No children allowed */
283
  children?: never;
284
}
285
```
286

287
**Usage Examples:**
288

289
```typescript
290
import { Divider, Stack, Text } from "@keystone-ui/core";
291

292
// Horizontal divider in vertical layout
293
<Stack gap="medium">
294
  <Text>Section 1</Text>
295
  <Divider />
296
  <Text>Section 2</Text>
297
</Stack>
298

299
// Vertical divider in horizontal layout  
300
<Inline gap="medium" align="center">
301
  <Text>Item 1</Text>
302
  <Divider orientation="vertical" />
303
  <Text>Item 2</Text>
304
</Inline>
305

306
// Custom colored divider
307
<Divider color="blue300" marginY="large" />
308
```
309

310
## Responsive Design
311

312
All layout components support responsive props using arrays that map to theme breakpoints:
313

314
```typescript
315
// Theme breakpoints: small: 576px, medium: 768px, large: 992px, xlarge: 1200px
316
<Box 
317
  padding={["small", "medium", "large", "xlarge"]}
318
  background={["white", "neutral50", "neutral100"]}
319
  width={["100%", "75%", "50%", "25%"]}
320
>
321
  Responsive box
322
</Box>
323
```
324

325
## Polymorphic Components
326

327
Layout components support the `as` prop to change the underlying HTML element or React component:
328

329
```typescript
330
<Box as="section">Section element</Box>
331
<Box as="article">Article element</Box>
332
<Box as={CustomComponent}>Custom component</Box>
333
<Stack as="nav">Navigation stack</Stack>
334
```