0
# Layout Components
1

2
Essential components for building terminal layouts using Flexbox-style positioning, text rendering with styling options, and specialized layout utilities.
3

4
## Capabilities
5

6
### Box Component
7

8
The essential layout component for building terminal UIs, equivalent to `<div style="display: flex">` in the browser.
9

10
```typescript { .api }
11
/**
12
 * Primary layout container component with Flexbox support
13
 * @param props - Layout and styling properties
14
 * @param children - Child components to render inside the box
15
 */
16
function Box(props: BoxProps & { children?: ReactNode }): JSX.Element;
17

18
interface BoxProps {
19
  // Position and display
20
  position?: "absolute" | "relative";
21
  display?: "flex" | "none";
22
  overflow?: "visible" | "hidden";
23
  overflowX?: "visible" | "hidden";
24
  overflowY?: "visible" | "hidden";
25
  
26
  // Flexbox layout
27
  flexDirection?: "row" | "column" | "row-reverse" | "column-reverse";  // default: "row"
28
  flexWrap?: "nowrap" | "wrap" | "wrap-reverse";                       // default: "nowrap"
29
  flexGrow?: number;                                                    // default: 0
30
  flexShrink?: number;                                                  // default: 1
31
  flexBasis?: number | string;
32
  justifyContent?: "flex-start" | "flex-end" | "center" | "space-between" | "space-around" | "space-evenly";
33
  alignItems?: "flex-start" | "center" | "flex-end" | "stretch";
34
  alignSelf?: "flex-start" | "center" | "flex-end" | "auto";
35
  
36
  // Dimensions
37
  width?: number | string;    // number = characters, string = percentage
38
  height?: number | string;   // number = lines, string = percentage
39
  minWidth?: number | string;
40
  minHeight?: number | string;
41
  
42
  // Spacing
43
  margin?: number;
44
  marginX?: number;          // horizontal margin
45
  marginY?: number;          // vertical margin  
46
  marginTop?: number;
47
  marginBottom?: number;
48
  marginLeft?: number;
49
  marginRight?: number;
50
  padding?: number;
51
  paddingX?: number;         // horizontal padding
52
  paddingY?: number;         // vertical padding
53
  paddingTop?: number;
54
  paddingBottom?: number;
55
  paddingLeft?: number;
56
  paddingRight?: number;
57
  gap?: number;              // gap between children
58
  columnGap?: number;        // gap between columns
59
  rowGap?: number;           // gap between rows
60
  
61
  // Borders
62
  borderStyle?: string;      // border style from cli-boxes
63
  borderTop?: boolean;       // default: true
64
  borderBottom?: boolean;    // default: true
65
  borderLeft?: boolean;      // default: true
66
  borderRight?: boolean;     // default: true
67
  borderColor?: string;
68
  borderTopColor?: string;
69
  borderBottomColor?: string;
70
  borderLeftColor?: string;
71
  borderRightColor?: string;
72
  borderDimColor?: boolean;
73
  borderTopDimColor?: boolean;
74
  borderBottomDimColor?: boolean;
75
  borderLeftDimColor?: boolean;
76
  borderRightDimColor?: boolean;
77
}
78
```
79

80
**Usage Examples:**
81

82
```typescript
83
import React from "react";
84
import { render, Box, Text } from "ink";
85

86
// Basic layout
87
function BasicLayout() {
88
  return (
89
    <Box flexDirection="column">
90
      <Box>
91
        <Text>Header</Text>
92
      </Box>
93
      <Box flexGrow={1}>
94
        <Text>Content</Text>
95
      </Box>
96
    </Box>
97
  );
98
}
99

100
// Centered content
101
function CenteredBox() {
102
  return (
103
    <Box justifyContent="center" alignItems="center" width={40} height={10}>
104
      <Text>Centered text</Text>
105
    </Box>
106
  );
107
}
108

109
// With borders and styling
110
function StyledBox() {
111
  return (
112
    <Box
113
      borderStyle="round"
114
      borderColor="blue"
115
      padding={2}
116
      margin={1}
117
    >
118
      <Text>Bordered content</Text>
119
    </Box>
120
  );
121
}
122
```
123

124
### Text Component
125

126
Component for displaying and styling text with color, formatting, and text wrapping options.
127

128
```typescript { .api }
129
/**
130
 * Text display component with comprehensive styling support
131
 * @param props - Text styling and content properties
132
 */
133
function Text(props: TextProps & { children?: ReactNode }): JSX.Element;
134

135
interface TextProps {
136
  /**
137
   * Text color using chalk color names or hex values
138
   */
139
  color?: string;
140
  
141
  /**
142
   * Background color using chalk color names or hex values
143
   */
144
  backgroundColor?: string;
145
  
146
  /**
147
   * Dim the text color (emit less light)
148
   * @default false
149
   */
150
  dimColor?: boolean;
151
  
152
  /**
153
   * Make text bold
154
   * @default false
155
   */
156
  bold?: boolean;
157
  
158
  /**
159
   * Make text italic
160
   * @default false
161
   */
162
  italic?: boolean;
163
  
164
  /**
165
   * Underline text
166
   * @default false
167
   */
168
  underline?: boolean;
169
  
170
  /**
171
   * Strike through text
172
   * @default false
173
   */
174
  strikethrough?: boolean;
175
  
176
  /**
177
   * Inverse background and foreground colors
178
   * @default false
179
   */
180
  inverse?: boolean;
181
  
182
  /**
183
   * Text wrapping behavior when width exceeds container
184
   * @default "wrap"
185
   */
186
  wrap?: "wrap" | "truncate-end" | "truncate" | "truncate-start" | "truncate-middle" | "end" | "middle";
187
}
188
```
189

190
**Usage Examples:**
191

192
```typescript
193
import React from "react";
194
import { render, Box, Text } from "ink";
195

196
// Styled text
197
function StyledText() {
198
  return (
199
    <Box flexDirection="column">
200
      <Text color="red" bold>Error: Something went wrong</Text>
201
      <Text color="green">✓ Success message</Text>
202
      <Text color="blue" italic>Information text</Text>
203
      <Text backgroundColor="yellow" color="black">Highlighted</Text>
204
      <Text dimColor>Dimmed text</Text>
205
      <Text underline>Underlined text</Text>
206
      <Text strikethrough>Crossed out</Text>
207
    </Box>
208
  );
209
}
210

211
// Text wrapping
212
function WrappedText() {
213
  return (
214
    <Box width={20}>
215
      <Text wrap="wrap">
216
        This is a long text that will wrap to multiple lines
217
      </Text>
218
    </Box>
219
  );
220
}
221

222
// Truncated text
223
function TruncatedText() {
224
  return (
225
    <Box width={15}>
226
      <Text wrap="truncate-end">
227
        This text will be truncated...
228
      </Text>
229
    </Box>
230
  );
231
}
232
```
233

234
### Static Component
235

236
Component that permanently renders output above everything else, useful for logs or completed tasks.
237

238
```typescript { .api }
239
/**
240
 * Renders items permanently above other output
241
 * @param props - Static rendering configuration
242
 */
243
function Static<T>(props: StaticProps<T>): JSX.Element;
244

245
interface StaticProps<T> {
246
  /**
247
   * Array of items to render using the render function
248
   */
249
  items: T[];
250
  
251
  /**
252
   * Styles to apply to container (Box styles)
253
   */
254
  style?: Styles;
255
  
256
  /**
257
   * Function to render each item in the items array
258
   * @param item - Current item being rendered
259
   * @param index - Index of the item in the array
260
   * @returns React node for the item
261
   */
262
  children: (item: T, index: number) => ReactNode;
263
}
264
```
265

266
**Usage Examples:**
267

268
```typescript
269
import React, { useState, useEffect } from "react";
270
import { render, Box, Text, Static } from "ink";
271

272
interface LogEntry {
273
  message: string;
274
  timestamp: Date;
275
  type: "info" | "error" | "success";
276
}
277

278
function LogViewer() {
279
  const [logs, setLogs] = useState<LogEntry[]>([]);
280
  const [currentTask, setCurrentTask] = useState("Processing...");
281
  
282
  useEffect(() => {
283
    // Simulate adding log entries
284
    const interval = setInterval(() => {
285
      setLogs(prev => [...prev, {
286
        message: `Task ${prev.length + 1} completed`,
287
        timestamp: new Date(),
288
        type: "success"
289
      }]);
290
    }, 1000);
291
    
292
    return () => clearInterval(interval);
293
  }, []);
294
  
295
  return (
296
    <Box flexDirection="column">
297
      <Static items={logs}>
298
        {(log, index) => (
299
          <Box key={index}>
300
            <Text color={log.type === "error" ? "red" : "green"}>
301
              [{log.timestamp.toTimeString()}] {log.message}
302
            </Text>
303
          </Box>
304
        )}
305
      </Static>
306
      
307
      <Box>
308
        <Text>Current: {currentTask}</Text>
309
      </Box>
310
    </Box>
311
  );
312
}
313
```
314

315
### Transform Component
316

317
Component for transforming string representation of child components before output.
318

319
```typescript { .api }
320
/**
321
 * Transform string output of child components
322
 * @param props - Transform configuration
323
 */
324
function Transform(props: TransformProps): JSX.Element;
325

326
interface TransformProps {
327
  /**
328
   * Function to transform the rendered string output
329
   * @param children - String representation of child components
330
   * @param index - Transform index (for multiple transforms)
331
   * @returns Transformed string
332
   */
333
  transform: (children: string, index: number) => string;
334
  
335
  children?: ReactNode;
336
}
337
```
338

339
**Usage Examples:**
340

341
```typescript
342
import React from "react";
343
import { render, Box, Text, Transform } from "ink";
344
import gradient from "gradient-string";
345

346
// Apply gradient effect
347
function GradientText() {
348
  return (
349
    <Transform transform={(output) => gradient.rainbow(output)}>
350
      <Text>Rainbow gradient text</Text>
351
    </Transform>
352
  );
353
}
354

355
// Add prefix to output
356
function PrefixedOutput() {
357
  return (
358
    <Transform transform={(output) => `>>> ${output}`}>
359
      <Box flexDirection="column">
360
        <Text>Line 1</Text>
361
        <Text>Line 2</Text>
362
      </Box>
363
    </Transform>
364
  );
365
}
366
```
367

368
### Newline Component
369

370
Component for inserting newline characters, must be used within Text components.
371

372
```typescript { .api }
373
/**
374
 * Insert newline characters
375
 * @param props - Newline configuration
376
 */
377
function Newline(props: NewlineProps): JSX.Element;
378

379
interface NewlineProps {
380
  /**
381
   * Number of newlines to insert
382
   * @default 1
383
   */
384
  count?: number;
385
}
386
```
387

388
**Usage Examples:**
389

390
```typescript
391
import React from "react";
392
import { render, Text, Newline } from "ink";
393

394
function MultilineText() {
395
  return (
396
    <Text>
397
      First line
398
      <Newline />
399
      Second line
400
      <Newline count={2} />
401
      Line after double newline
402
    </Text>
403
  );
404
}
405
```
406

407
### Spacer Component
408

409
Flexible space component that expands along the major axis of its containing layout.
410

411
```typescript { .api }
412
/**
413
 * Flexible space that fills available space
414
 * Note: Spacer accepts no props and simply renders a Box with flexGrow={1}
415
 */
416
function Spacer(): JSX.Element;
417
```
418

419
**Usage Examples:**
420

421
```typescript
422
import React from "react";
423
import { render, Box, Text, Spacer } from "ink";
424

425
// Right-aligned text
426
function RightAligned() {
427
  return (
428
    <Box>
429
      <Spacer />
430
      <Text>Right aligned</Text>
431
    </Box>
432
  );
433
}
434

435
// Space between elements
436
function SpaceBetween() {
437
  return (
438
    <Box>
439
      <Text>Left</Text>
440
      <Spacer />
441
      <Text>Right</Text>
442
    </Box>
443
  );
444
}
445

446
// Vertical spacing
447
function VerticalSpacing() {
448
  return (
449
    <Box flexDirection="column" height={10}>
450
      <Text>Top</Text>
451
      <Spacer />
452
      <Text>Bottom</Text>
453
    </Box>
454
  );
455
}
456
```