<Box>

<Box> is an essential Ink component to build your layout. It's like <div style="display: flex"> in the browser.

import {render, Box, Text} from 'ink';

const Example = () => (
	<Box margin={2}>
		<Text>This is a box with margin</Text>
	</Box>
);

render(<Example />);

Props

Dimensions

width

Type: number string

Width of the element in spaces. You can also set it as a percentage, which will calculate the width based on the width of the parent element.

<Box width={4}>
	<Text>X</Text>
</Box>
//=> 'X   '

<Box width={10}>
	<Box width="50%">
		<Text>X</Text>
	</Box>
	<Text>Y</Text>
</Box>
//=> 'X    Y'

height

Type: number string

Height of the element in lines (rows). You can also set it as a percentage, which will calculate the height based on the height of the parent element.

<Box height={4}>
	<Text>X</Text>
</Box>
//=> 'X\n\n\n'

<Box height={6} flexDirection="column">
	<Box height="50%">
		<Text>X</Text>
	</Box>
	<Text>Y</Text>
</Box>
//=> 'X\n\n\nY\n\n'

minWidth

Type: number

Sets a minimum width of the element. Percentages aren't supported yet; see https://github.com/facebook/yoga/issues/872.

minHeight

Type: number

Sets a minimum height of the element. Percentages aren't supported yet; see https://github.com/facebook/yoga/issues/872.

Padding

paddingTop

Type: number
Default: 0

Top padding.

paddingBottom

Type: number
Default: 0

Bottom padding.

paddingLeft

Type: number
Default: 0

Left padding.

paddingRight

Type: number
Default: 0

Right padding.

paddingX

Type: number
Default: 0

Horizontal padding. Equivalent to setting paddingLeft and paddingRight.

paddingY

Type: number
Default: 0

Vertical padding. Equivalent to setting paddingTop and paddingBottom.

padding

Type: number
Default: 0

Padding on all sides. Equivalent to setting paddingTop, paddingBottom, paddingLeft and paddingRight.

<Box paddingTop={2}><Text>Top</Text></Box>
<Box paddingBottom={2}><Text>Bottom</Text></Box>
<Box paddingLeft={2}><Text>Left</Text></Box>
<Box paddingRight={2}><Text>Right</Text></Box>
<Box paddingX={2}><Text>Left and right</Text></Box>
<Box paddingY={2}><Text>Top and bottom</Text></Box>
<Box padding={2}><Text>Top, bottom, left and right</Text></Box>

Margin

marginTop

Type: number
Default: 0

Top margin.

marginBottom

Type: number
Default: 0

Bottom margin.

marginLeft

Type: number
Default: 0

Left margin.

marginRight

Type: number
Default: 0

Right margin.

marginX

Type: number
Default: 0

Horizontal margin. Equivalent to setting marginLeft and marginRight.

marginY

Type: number
Default: 0

Vertical margin. Equivalent to setting marginTop and marginBottom.

margin

Type: number
Default: 0

Margin on all sides. Equivalent to setting marginTop, marginBottom, marginLeft and marginRight.

<Box marginTop={2}><Text>Top</Text></Box>
<Box marginBottom={2}><Text>Bottom</Text></Box>
<Box marginLeft={2}><Text>Left</Text></Box>
<Box marginRight={2}><Text>Right</Text></Box>
<Box marginX={2}><Text>Left and right</Text></Box>
<Box marginY={2}><Text>Top and bottom</Text></Box>
<Box margin={2}><Text>Top, bottom, left and right</Text></Box>

Gap

gap

Type: number
Default: 0

Size of the gap between an element's columns and rows. A shorthand for columnGap and rowGap.

<Box gap={1} width={3} flexWrap="wrap">
	<Text>A</Text>
	<Text>B</Text>
	<Text>C</Text>
</Box>
// A B
//
// C

columnGap

Type: number
Default: 0

Size of the gap between an element's columns.

<Box columnGap={1}>
	<Text>A</Text>
	<Text>B</Text>
</Box>
// A B

rowGap

Type: number
Default: 0

Size of the gap between an element's rows.

<Box flexDirection="column" rowGap={1}>
	<Text>A</Text>
	<Text>B</Text>
</Box>
// A
//
// B

Flexbox Layout

flexGrow

Type: number
Default: 0

See flex-grow.

<Box>
	<Text>Label:</Text>
	<Box flexGrow={1}>
		<Text>Fills all remaining space</Text>
	</Box>
</Box>

flexShrink

Type: number
Default: 1

See flex-shrink.

<Box width={20}>
	<Box flexShrink={2} width={10}>
		<Text>Will be 1/4</Text>
	</Box>
	<Box width={10}>
		<Text>Will be 3/4</Text>
	</Box>
</Box>

flexBasis

Type: number string

See flex-basis.

<Box width={6}>
	<Box flexBasis={3}>
		<Text>X</Text>
	</Box>
	<Text>Y</Text>
</Box>
//=> 'X  Y'

<Box width={6}>
	<Box flexBasis="50%">
		<Text>X</Text>
	</Box>
	<Text>Y</Text>
</Box>
//=> 'X  Y'

flexDirection

Type: string
Allowed values: row row-reverse column column-reverse

See flex-direction.

<Box>
	<Box marginRight={1}>
		<Text>X</Text>
	</Box>
	<Text>Y</Text>
</Box>
// X Y

<Box flexDirection="row-reverse">
	<Text>X</Text>
	<Box marginRight={1}>
		<Text>Y</Text>
	</Box>
</Box>
// Y X

<Box flexDirection="column">
	<Text>X</Text>
	<Text>Y</Text>
</Box>
// X
// Y

<Box flexDirection="column-reverse">
	<Text>X</Text>
	<Text>Y</Text>
</Box>
// Y
// X

flexWrap

Type: string
Allowed values: nowrap wrap wrap-reverse

See flex-wrap.

<Box width={2} flexWrap="wrap">
	<Text>A</Text>
	<Text>BC</Text>
</Box>
// A
// B C

<Box flexDirection="column" height={2} flexWrap="wrap">
	<Text>A</Text>
	<Text>B</Text>
	<Text>C</Text>
</Box>
// A C
// B

alignItems

Type: string
Allowed values: flex-start center flex-end

See align-items.

<Box alignItems="flex-start">
	<Box marginRight={1}>
		<Text>X</Text>
	</Box>
	<Text>
		A
		<Newline/>
		B
		<Newline/>
		C
	</Text>
</Box>
// X A
//   B
//   C

<Box alignItems="center">
	<Box marginRight={1}>
		<Text>X</Text>
	</Box>
	<Text>
		A
		<Newline/>
		B
		<Newline/>
		C
	</Text>
</Box>
//   A
// X B
//   C

<Box alignItems="flex-end">
	<Box marginRight={1}>
		<Text>X</Text>
	</Box>
	<Text>
		A
		<Newline/>
		B
		<Newline/>
		C
	</Text>
</Box>
//   A
//   B
// X C

alignSelf

Type: string
Default: auto
Allowed values: auto flex-start center flex-end

See align-self.

<Box height={3}>
	<Box alignSelf="flex-start">
		<Text>X</Text>
	</Box>
</Box>
// X
//
//

<Box height={3}>
	<Box alignSelf="center">
		<Text>X</Text>
	</Box>
</Box>
//
// X
//

<Box height={3}>
	<Box alignSelf="flex-end">
		<Text>X</Text>
	</Box>
</Box>
//
//
// X

justifyContent

Type: string
Allowed values: flex-start center flex-end space-between space-around space-evenly

See justify-content.

<Box justifyContent="flex-start">
	<Text>X</Text>
</Box>
// [X      ]

<Box justifyContent="center">
	<Text>X</Text>
</Box>
// [   X   ]

<Box justifyContent="flex-end">
	<Text>X</Text>
</Box>
// [      X]

<Box justifyContent="space-between">
	<Text>X</Text>
	<Text>Y</Text>
</Box>
// [X      Y]

<Box justifyContent="space-around">
	<Text>X</Text>
	<Text>Y</Text>
</Box>
// [  X   Y  ]

<Box justifyContent="space-evenly">
	<Text>X</Text>
	<Text>Y</Text>
</Box>
// [   X   Y   ]

Visibility

display

Type: string
Allowed values: flex none
Default: flex

Set this property to none to hide the element.

overflowX

Type: string
Allowed values: visible hidden
Default: visible

Behavior for an element's overflow in the horizontal direction.

overflowY

Type: string
Allowed values: visible hidden
Default: visible

Behavior for an element's overflow in the vertical direction.

overflow

Type: string
Allowed values: visible hidden
Default: visible

A shortcut for setting overflowX and overflowY at the same time.

Borders

borderStyle

Type: string
Allowed values: single double round bold singleDouble doubleSingle classic | BoxStyle

Add a border with a specified style. If borderStyle is undefined (the default), no border will be added. Ink uses border styles from the cli-boxes module.

<Box flexDirection="column">
	<Box>
		<Box borderStyle="single" marginRight={2}>
			<Text>single</Text>
		</Box>

		<Box borderStyle="double" marginRight={2}>
			<Text>double</Text>
		</Box>

		<Box borderStyle="round" marginRight={2}>
			<Text>round</Text>
		</Box>

		<Box borderStyle="bold">
			<Text>bold</Text>
		</Box>
	</Box>

	<Box marginTop={1}>
		<Box borderStyle="singleDouble" marginRight={2}>
			<Text>singleDouble</Text>
		</Box>

		<Box borderStyle="doubleSingle" marginRight={2}>
			<Text>doubleSingle</Text>
		</Box>

		<Box borderStyle="classic">
			<Text>classic</Text>
		</Box>
	</Box>
</Box>

<img src="../../media/box-borderStyle.jpg" width="521">

Alternatively, pass a custom border style like so:

<Box
	borderStyle={{
		topLeft: '↘',
		top: '↓',
		topRight: '↙',
		left: '→',
		bottomLeft: '↗',
		bottom: '↑',
		bottomRight: '↖',
		right: '←'
	}}
>
	<Text>Custom</Text>
</Box>

See example in examples/borders.

borderColor

Type: string

Change border color. A shorthand for setting borderTopColor, borderRightColor, borderBottomColor, and borderLeftColor.

<Box borderStyle="round" borderColor="green">
	<Text>Green Rounded Box</Text>
</Box>

<img src="../../media/box-borderColor.jpg" width="228">

borderTopColor

Type: string

Change top border color. Accepts the same values as color in <Text> component.

<Box borderStyle="round" borderTopColor="green">
	<Text>Hello world</Text>
</Box>

borderRightColor

Type: string

Change right border color. Accepts the same values as color in <Text> component.

borderBottomColor

Type: string

Change bottom border color. Accepts the same values as color in <Text> component.

borderLeftColor

Type: string

Change left border color. Accepts the same values as color in <Text> component.

borderDimColor

Type: boolean
Default: false

Dim the border color. A shorthand for setting borderTopDimColor, borderBottomDimColor, borderLeftDimColor, and borderRightDimColor.

borderTopDimColor

Type: boolean
Default: false

Dim the top border color.

borderBottomDimColor

Type: boolean
Default: false

Dim the bottom border color.

borderLeftDimColor

Type: boolean
Default: false

Dim the left border color.

borderRightDimColor

Type: boolean
Default: false

Dim the right border color.

borderTop

Type: boolean
Default: true

Determines whether top border is visible.

borderRight

Type: boolean
Default: true

Determines whether right border is visible.

borderBottom

Type: boolean
Default: true

Determines whether bottom border is visible.

borderLeft

Type: boolean
Default: true

Determines whether left border is visible.

Background

backgroundColor

Type: string

Background color for the element.

Accepts the same values as color in the <Text> component.

<Box flexDirection="column">
	<Box backgroundColor="red" width={20} height={5} alignSelf="flex-start">
		<Text>Red background</Text>
	</Box>

	<Box backgroundColor="#FF8800" width={20} height={3} marginTop={1} alignSelf="flex-start">
		<Text>Orange background</Text>
	</Box>

	<Box backgroundColor="rgb(0, 255, 0)" width={20} height={3} marginTop={1} alignSelf="flex-start">
		<Text>Green background</Text>
	</Box>
</Box>

The background color fills the entire <Box> area and is inherited by child <Text> components unless they specify their own backgroundColor.

<Box backgroundColor="blue" alignSelf="flex-start">
	<Text>Blue inherited </Text>
	<Text backgroundColor="yellow">Yellow override </Text>
	<Text>Blue inherited again</Text>
</Box>

Background colors work with borders and padding:

<Box backgroundColor="cyan" borderStyle="round" padding={1} alignSelf="flex-start">
	<Text>Background with border and padding</Text>
</Box>

See example in examples/box-backgrounds.