0
# Layout Components
1

2
Core layout and structure components for building responsive user interfaces with flexbox-based layouts and precise spacing control.
3

4
## Capabilities
5

6
### Box Component
7

8
The fundamental layout component that renders as a View with styling capabilities.
9

10
```typescript { .api }
11
/**
12
 * Basic layout container component with styling props
13
 * @param props - Box component props including styling and layout options
14
 * @returns JSX element representing a styled container 
15
 */
16
function Box(props: IBoxProps): JSX.Element;
17

18
interface IBoxProps extends StyledProps {
19
  children?: React.ReactNode;
20
  // Flexbox properties
21
  alignItems?: ResponsiveValue<"flex-start" | "flex-end" | "center" | "stretch" | "baseline">;
22
  justifyContent?: ResponsiveValue<"flex-start" | "flex-end" | "center" | "space-between" | "space-around" | "space-evenly">;
23
  flex?: ResponsiveValue<number>;
24
  flexDirection?: ResponsiveValue<"row" | "column" | "row-reverse" | "column-reverse">;
25
  flexWrap?: ResponsiveValue<"wrap" | "nowrap" | "wrap-reverse">;
26
  // Layout properties
27
  position?: ResponsiveValue<"absolute" | "relative">;
28
  top?: ResponsiveValue<string | number>;
29
  right?: ResponsiveValue<string | number>;
30
  bottom?: ResponsiveValue<string | number>;
31
  left?: ResponsiveValue<string | number>;
32
  zIndex?: ResponsiveValue<number>;
33
}
34
```
35

36
**Usage Examples:**
37

38
```typescript
39
import { Box } from "native-base";
40

41
// Basic container
42
<Box bg="blue.500" p={4}>
43
  <Text>Content</Text>
44
</Box>
45

46
// Flexbox layout
47
<Box flex={1} alignItems="center" justifyContent="center">
48
  <Text>Centered content</Text>
49
</Box>
50

51
// Responsive properties
52
<Box 
53
  w={{ base: "100%", md: "50%" }}
54
  bg={{ base: "red.100", dark: "red.800" }}
55
>
56
  <Text>Responsive box</Text>
57
</Box>
58
```
59

60
### Flex Component
61

62
Shorthand for Box with display flex properties.
63

64
```typescript { .api }
65
/**
66
 * Flex container component with flexbox properties
67
 * @param props - Flex component props extending Box props
68
 * @returns JSX element with flex display
69
 */
70
function Flex(props: IFlexProps): JSX.Element;
71

72
interface IFlexProps extends IBoxProps {
73
  direction?: ResponsiveValue<"row" | "column" | "row-reverse" | "column-reverse">;
74
  wrap?: ResponsiveValue<"wrap" | "nowrap" | "wrap-reverse">;
75
  align?: ResponsiveValue<"flex-start" | "flex-end" | "center" | "stretch" | "baseline">;
76
  justify?: ResponsiveValue<"flex-start" | "flex-end" | "center" | "space-between" | "space-around" | "space-evenly">;
77
}
78
```
79

80
### Stack Components
81

82
Layout components for organizing children with consistent spacing.
83

84
```typescript { .api }
85
/**
86
 * Generic stack component for arranging children with spacing
87
 * @param props - Stack component props
88
 * @returns JSX element with children arranged in specified direction
89
 */
90
function Stack(props: IStackProps): JSX.Element;
91

92
/**
93
 * Vertical stack component arranging children vertically
94
 * @param props - Stack component props
95
 * @returns JSX element with vertical layout
96
 */
97
function VStack(props: IStackProps): JSX.Element;
98

99
/**
100
 * Horizontal stack component arranging children horizontally  
101
 * @param props - Stack component props
102
 * @returns JSX element with horizontal layout
103
 */
104
function HStack(props: IStackProps): JSX.Element;
105

106
/**
107
 * Z-axis stack component for layering children
108
 * @param props - ZStack component props
109
 * @returns JSX element with z-index based layering
110
 */
111
function ZStack(props: IZStackProps): JSX.Element;
112

113
interface IStackProps extends IBoxProps {
114
  space?: ResponsiveValue<string | number>;
115
  divider?: JSX.Element;
116
  reversed?: boolean;
117
}
118

119
interface IZStackProps extends IBoxProps {
120
  reversed?: boolean;
121
}
122
```
123

124
**Usage Examples:**
125

126
```typescript
127
import { VStack, HStack, Text, Button } from "native-base";
128

129
// Vertical stack with spacing
130
<VStack space={4} alignItems="center">
131
  <Text>Item 1</Text>
132
  <Text>Item 2</Text>
133
  <Button>Action</Button>
134
</VStack>
135

136
// Horizontal stack with divider
137
<HStack space={2} divider={<Divider />}>
138
  <Text>Left</Text>
139
  <Text>Right</Text>
140
</HStack>
141
```
142

143
### Center Component
144

145
Component for centering content both horizontally and vertically.
146

147
```typescript { .api }
148
/**
149
 * Centers its children both horizontally and vertically
150
 * @param props - Center component props
151
 * @returns JSX element with centered content
152
 */
153
function Center(props: ICenterProps): JSX.Element;
154

155
/**
156
 * Square container that centers content
157
 * @param props - Square component props
158
 * @returns JSX element with equal width/height
159
 */
160
function Square(props: ISquareProps): JSX.Element;
161

162
/**
163
 * Circular container that centers content
164
 * @param props - Circle component props  
165
 * @returns JSX element with circular shape
166
 */
167
function Circle(props: ICircleProps): JSX.Element;
168

169
interface ICenterProps extends IBoxProps {}
170

171
interface ISquareProps extends ICenterProps {
172
  size?: ResponsiveValue<string | number>;
173
}
174

175
interface ICircleProps extends ISquareProps {}
176
```
177

178
### Column and Row Components
179

180
Simple layout components for basic grid-like arrangements.
181

182
```typescript { .api }
183
/**
184
 * Column layout component
185
 * @param props - Box component props
186
 * @returns JSX element with column layout
187
 */
188
function Column(props: IBoxProps): JSX.Element;
189

190
/**
191
 * Row layout component
192
 * @param props - Box component props
193
 * @returns JSX element with row layout
194
 */
195
function Row(props: IBoxProps): JSX.Element;
196
```
197

198
### Container Component
199

200
Responsive container component with max-width constraints.
201

202
```typescript { .api }
203
/**
204
 * Responsive container with max-width constraints
205
 * @param props - Container component props
206
 * @returns JSX element with responsive container behavior
207
 */
208
function Container(props: IContainerProps): JSX.Element;
209

210
interface IContainerProps extends IBoxProps {
211
  centerContent?: boolean;
212
  maxW?: ResponsiveValue<string | number>;
213
}
214
```
215

216
### Spacer Component
217

218
Flexible space component that expands to fill available space.
219

220
```typescript { .api }
221
/**
222
 * Flexible spacer component that fills available space
223
 * @returns JSX element that expands to fill space
224
 */
225
function Spacer(): JSX.Element;
226
```
227

228
### Aspect Ratio Component
229

230
Component for maintaining specific aspect ratios.
231

232
```typescript { .api }
233
/**
234
 * Maintains aspect ratio for its children
235
 * @param props - AspectRatio component props
236
 * @returns JSX element with specified aspect ratio
237
 */
238
function AspectRatio(props: IAspectRatioProps): JSX.Element;
239

240
interface IAspectRatioProps extends IBoxProps {
241
  ratio?: number;
242
}
243
```
244

245
**Usage Example:**
246

247
```typescript
248
import { AspectRatio, Image } from "native-base";
249

250
<AspectRatio w="100%" ratio={16/9}>
251
  <Image source={{ uri: "https://example.com/image.jpg" }} alt="Image" />
252
</AspectRatio>
253
```
254

255
### Divider Component
256

257
Visual separator component for organizing content.
258

259
```typescript { .api }
260
/**
261
 * Visual divider for separating content
262
 * @param props - Divider component props
263
 * @returns JSX element representing a divider line
264
 */
265
function Divider(props: IDividerProps): JSX.Element;
266

267
interface IDividerProps extends IBoxProps {
268
  orientation?: "horizontal" | "vertical";
269
  thickness?: ResponsiveValue<string | number>;
270
}
271
```
272

273
### Wrap Component
274

275
Component for wrapping children with flexible layouts.
276

277
```typescript { .api }
278
/**
279
 * Wraps children with flexible layout and spacing
280
 * @param props - Wrap component props
281
 * @returns JSX element with wrapped layout
282
 */
283
function Wrap(props: IWrapProps): JSX.Element;
284

285
interface IWrapProps extends IBoxProps {
286
  spacing?: ResponsiveValue<string | number>;
287
  spacingX?: ResponsiveValue<string | number>;
288
  spacingY?: ResponsiveValue<string | number>;
289
  shouldWrapChildren?: boolean;
290
}
291
```
292

293
### SimpleGrid Component
294

295
Simple grid layout component with responsive columns.
296

297
```typescript { .api }
298
/**
299
 * Simple grid layout with responsive column support
300
 * @param props - SimpleGrid component props
301
 * @returns JSX element with grid layout
302
 */
303
function SimpleGrid(props: ISimpleGridProps): JSX.Element;
304

305
interface ISimpleGridProps extends IBoxProps {
306
  columns?: ResponsiveValue<number>;
307
  spacing?: ResponsiveValue<string | number>;
308
  spacingX?: ResponsiveValue<string | number>;
309
  spacingY?: ResponsiveValue<string | number>;
310
  minChildWidth?: ResponsiveValue<string | number>;
311
}
312
```
313

314
**Usage Example:**
315

316
```typescript
317
import { SimpleGrid, Box } from "native-base";
318

319
<SimpleGrid columns={2} spacing={4}>
320
  <Box bg="red.100" p={4}>Item 1</Box>
321
  <Box bg="blue.100" p={4}>Item 2</Box>
322
  <Box bg="green.100" p={4}>Item 3</Box>
323
  <Box bg="yellow.100" p={4}>Item 4</Box>
324
</SimpleGrid>
325
```
326

327
### Pressable Component
328

329
Fundamental interaction component that wraps React Native's Pressable with enhanced styling and state management capabilities.
330

331
```typescript { .api }
332
/**
333
 * Interactive component that responds to touch and keyboard events
334
 * @param props - Pressable component props
335
 * @returns JSX element representing a pressable interaction area
336
 */
337
function Pressable(props: IPressableProps): JSX.Element;
338

339
interface IPressableProps extends PressableProps, StyledProps {
340
  children?: React.ReactNode | ((state: PressableState) => React.ReactNode);
341
  onPress?: () => void;
342
  onPressIn?: () => void;
343
  onPressOut?: () => void;
344
  onHoverIn?: () => void;
345
  onHoverOut?: () => void;
346
  onFocus?: () => void;
347
  onBlur?: () => void;
348
  isDisabled?: boolean;
349
  isHovered?: boolean;
350
  isPressed?: boolean;
351
  isFocused?: boolean;
352
  isFocusVisible?: boolean;
353
  _hover?: Partial<IPressableProps>;
354
  _pressed?: Partial<IPressableProps>;
355
  _focus?: Partial<IPressableProps>;
356
  _focusVisible?: Partial<IPressableProps>;
357
  _disabled?: Partial<IPressableProps>;
358
}
359

360
interface PressableState {
361
  isPressed: boolean;
362
  isHovered: boolean;
363
  isFocused: boolean;
364
}
365
```
366

367
**Usage Examples:**
368

369
```typescript
370
import { Pressable, Box, Text } from "native-base";
371

372
// Basic pressable area
373
<Pressable onPress={() => console.log("Pressed!")}>
374
  <Box p={4} bg="blue.500" rounded="md">
375
    <Text color="white">Press me</Text>
376
  </Box>
377
</Pressable>
378

379
// Pressable with state-based styling
380
<Pressable
381
  onPress={() => console.log("Card pressed")}
382
  _pressed={{ bg: "gray.100" }}
383
  _hover={{ bg: "gray.50" }}
384
  _focus={{ bg: "gray.100", borderColor: "blue.500", borderWidth: 2 }}
385
>
386
  <Box p={4} borderWidth={1} borderColor="gray.200" rounded="lg">
387
    <Text>Interactive card</Text>
388
  </Box>
389
</Pressable>
390

391
// Pressable with render function for dynamic children
392
<Pressable>
393
  {({ isPressed, isHovered }) => (
394
    <Box 
395
      p={4} 
396
      bg={isPressed ? "red.600" : isHovered ? "red.500" : "red.400"}
397
      rounded="md"
398
      transform={[{ scale: isPressed ? 0.95 : 1 }]}
399
    >
400
      <Text color="white">
401
        {isPressed ? "Pressing..." : "Press me"}
402
      </Text>
403
    </Box>
404
  )}
405
</Pressable>
406

407
// Disabled pressable
408
<Pressable 
409
  isDisabled 
410
  _disabled={{ opacity: 0.5 }}
411
  onPress={() => console.log("This won't fire")}
412
>
413
  <Box p={4} bg="gray.300" rounded="md">
414
    <Text>Disabled button</Text>
415
  </Box>
416
</Pressable>
417
```
418

419
### Hidden Component
420

421
Utility component for conditionally hiding content based on breakpoints, color modes, or platforms.
422

423
```typescript { .api }
424
/**
425
 * Utility component for responsive and conditional visibility
426
 * @param props - Hidden component props
427
 * @returns JSX element that conditionally renders children
428
 */
429
function Hidden(props: IHiddenProps): JSX.Element;
430

431
interface IHiddenProps {
432
  from?: "base" | "sm" | "md" | "lg" | "xl";
433
  till?: "base" | "sm" | "md" | "lg" | "xl";
434
  only?: "base" | "sm" | "md" | "lg" | "xl" | Array<"base" | "sm" | "md" | "lg" | "xl">;
435
  colorMode?: "light" | "dark";
436
  platform?: "ios" | "android" | "web" | Array<"ios" | "android" | "web">;
437
  children: React.ReactElement | null;
438
  isSSR?: boolean;
439
}
440
```
441

442
**Usage Examples:**
443

444
```typescript
445
import { Hidden, Box, Text } from "native-base";
446

447
// Hide content on specific breakpoints
448
<Hidden from="md">
449
  <Box p={4} bg="blue.500">
450
    <Text color="white">Hidden on medium screens and up</Text>
451
  </Box>
452
</Hidden>
453

454
<Hidden till="sm">
455
  <Box p={4} bg="green.500">
456
    <Text color="white">Hidden until small screens</Text>
457
  </Box>
458
</Hidden>
459

460
// Hide content only on specific breakpoints
461
<Hidden only={["sm", "md"]}>
462
  <Box p={4} bg="red.500">
463
    <Text color="white">Hidden only on small and medium screens</Text>
464
  </Box>
465
</Hidden>
466

467
// Hide content based on color mode
468
<Hidden colorMode="dark">
469
  <Box p={4} bg="yellow.400">
470
    <Text>Only visible in light mode</Text>
471
  </Box>
472
</Hidden>
473

474
<Hidden colorMode="light">
475
  <Box p={4} bg="gray.700">
476
    <Text color="white">Only visible in dark mode</Text>
477
  </Box>
478
</Hidden>
479

480
// Hide content on specific platforms
481
<Hidden platform="web">
482
  <Box p={4} bg="purple.500">
483
    <Text color="white">Hidden on web, visible on mobile</Text>
484
  </Box>
485
</Hidden>
486

487
<Hidden platform={["ios", "android"]}>
488
  <Box p={4} bg="orange.500">
489
    <Text color="white">Only visible on web</Text>
490
  </Box>
491
</Hidden>
492

493
// Complex responsive layout
494
<Box>
495
  <Hidden till="md">
496
    <Text fontSize="xs">Mobile layout</Text>
497
  </Hidden>
498
  <Hidden from="md" till="lg">
499
    <Text fontSize="sm">Tablet layout</Text>
500
  </Hidden>
501
  <Hidden from="lg">
502
    <Text fontSize="md">Desktop layout</Text>
503
  </Hidden>
504
</Box>
505
```