Yoga Layout

Flexbox layout engine integration for OpenTUI components

OpenTUI uses Yoga Layout (v3.2.1) for flexbox-based layout calculations. All layout properties are available on renderable components through the LayoutOptions interface.

Flex Container Properties

flexDirection · FlexDirectionString · default: "column"

Defines the main axis direction of flex items.

Values: "column" | "column-reverse" | "row" | "row-reverse"

<Box flexDirection="row">
  {/* Children laid out horizontally */}
</Box>

flexWrap · WrapString · default: "no-wrap"

Controls whether flex items wrap to multiple lines.

Values: "no-wrap" | "wrap" | "wrap-reverse"

<Box flexWrap="wrap">
  {/* Items wrap to next line when needed */}
</Box>

alignItems · AlignString · default: "stretch"

Aligns flex items along the cross axis.

Values: "auto" | "flex-start" | "center" | "flex-end" | "stretch" | "baseline" | "space-between" | "space-around" | "space-evenly"

<Box alignItems="center">
  {/* Items centered on cross axis */}
</Box>

justifyContent · JustifyString · default: "flex-start"

Aligns flex items along the main axis.

Values: "flex-start" | "center" | "flex-end" | "space-between" | "space-around" | "space-evenly"

<Box justifyContent="space-between">
  {/* Space distributed between items */}
</Box>

Flex Item Properties

flexGrow · number · default: "0"

Defines how much a flex item should grow relative to siblings.

<Box flexGrow={1}>
  {/* Takes up available space */}
</Box>

flexShrink · number · default: "1"

Defines how much a flex item should shrink relative to siblings.

Note: Defaults to 0 when explicit width or height is set.

<Box flexShrink={0}>
  {/* Won't shrink below content size */}
</Box>

flexBasis · number | 'auto' · default: "auto"

Defines the default size of a flex item before remaining space is distributed.

<Box flexBasis={100}>
  {/* Base size of 100 units */}
</Box>

alignSelf · AlignString · default: "auto"

Overrides the parent’s alignItems for this specific item.

Values: "auto" | "flex-start" | "center" | "flex-end" | "stretch" | "baseline" | "space-between" | "space-around" | "space-evenly"

<Box alignSelf="flex-end">
  {/* Aligned to end, regardless of parent alignItems */}
</Box>

Size Properties

width · number | 'auto' | `${number}%` · default: "auto"

Sets the width of the component.

<Box width={200}>
  {/* Fixed width of 200 units */}
</Box>
<Box width="50%">
  {/* 50% of parent width */}
</Box>

height · number | 'auto' | `${number}%` · default: "auto"

Sets the height of the component.

<Box height={100}>
  {/* Fixed height of 100 units */}
</Box>
<Box height="auto">
  {/* Height based on content */}
</Box>

minWidth · number | 'auto' | `${number}%`

Sets the minimum width constraint.

<Box minWidth={50}>
  {/* Won't shrink below 50 units */}
</Box>

minHeight · number | 'auto' | `${number}%`

Sets the minimum height constraint.

<Box minHeight={30}>
  {/* Won't shrink below 30 units */}
</Box>

maxWidth · number | 'auto' | `${number}%`

Sets the maximum width constraint.

<Box maxWidth={500}>
  {/* Won't grow beyond 500 units */}
</Box>

maxHeight · number | 'auto' | `${number}%`

Sets the maximum height constraint.

<Box maxHeight={300}>
  {/* Won't grow beyond 300 units */}
</Box>

Position Properties

position · PositionTypeString · default: "relative"

Defines the positioning type of the component.

Values: "static" | "relative" | "absolute"

<Box position="absolute" top={0} left={0}>
  {/* Positioned absolutely from parent */}
</Box>

top · number | 'auto' | `${number}%`

Sets the top position offset.

<Box position="absolute" top={10}>
  {/* 10 units from top */}
</Box>

right · number | 'auto' | `${number}%`

Sets the right position offset.

<Box position="absolute" right={10}>
  {/* 10 units from right */}
</Box>

bottom · number | 'auto' | `${number}%`

Sets the bottom position offset.

<Box position="absolute" bottom={10}>
  {/* 10 units from bottom */}
</Box>

left · number | 'auto' | `${number}%`

Sets the left position offset.

<Box position="absolute" left={10}>
  {/* 10 units from left */}
</Box>

Spacing Properties

Margin

margin · number | 'auto' | `${number}%`

Sets margin on all sides.

<Box margin={10}>
  {/* 10 units of margin on all sides */}
</Box>

marginX · number | 'auto' | `${number}%`

Sets horizontal margin (left and right).

<Box marginX={20}>
  {/* 20 units of margin on left and right */}
</Box>

marginY · number | 'auto' | `${number}%`

Sets vertical margin (top and bottom).

<Box marginY={15}>
  {/* 15 units of margin on top and bottom */}
</Box>

marginTop · number | 'auto' | `${number}%`

Sets top margin.

<Box marginTop={10}>
  {/* 10 units of margin on top */}
</Box>

marginRight · number | 'auto' | `${number}%`

Sets right margin.

<Box marginRight={10}>
  {/* 10 units of margin on right */}
</Box>

marginBottom · number | 'auto' | `${number}%`

Sets bottom margin.

<Box marginBottom={10}>
  {/* 10 units of margin on bottom */}
</Box>

marginLeft · number | 'auto' | `${number}%`

Sets left margin.

<Box marginLeft={10}>
  {/* 10 units of margin on left */}
</Box>

Padding

padding · number | `${number}%`

Sets padding on all sides.

<Box padding={10}>
  {/* 10 units of padding on all sides */}
</Box>

paddingX · number | `${number}%`

Sets horizontal padding (left and right).

<Box paddingX={20}>
  {/* 20 units of padding on left and right */}
</Box>

paddingY · number | `${number}%`

Sets vertical padding (top and bottom).

<Box paddingY={15}>
  {/* 15 units of padding on top and bottom */}
</Box>

paddingTop · number | `${number}%`

Sets top padding.

<Box paddingTop={10}>
  {/* 10 units of padding on top */}
</Box>

paddingRight · number | `${number}%`

Sets right padding.

<Box paddingRight={10}>
  {/* 10 units of padding on right */}
</Box>

paddingBottom · number | `${number}%`

Sets bottom padding.

<Box paddingBottom={10}>
  {/* 10 units of padding on bottom */}
</Box>

paddingLeft · number | `${number}%`

Sets left padding.

<Box paddingLeft={10}>
  {/* 10 units of padding on left */}
</Box>

Overflow

overflow · OverflowString · default: "visible"

Controls how content that overflows the component’s box is handled.

Values: "visible" | "hidden" | "scroll"

<Box overflow="hidden" width={100} height={100}>
  {/* Content clipped to bounds */}
</Box>

Other Properties

enableLayout · boolean · default: "true"

Controls whether layout calculations are enabled for this component.

<Box enableLayout={false}>
  {/* Layout calculations disabled */}
</Box>

Type Definitions

interface LayoutOptions {
  // Flex container
  flexDirection?: "column" | "column-reverse" | "row" | "row-reverse"
  flexWrap?: "no-wrap" | "wrap" | "wrap-reverse"
  alignItems?: "auto" | "flex-start" | "center" | "flex-end" | "stretch" | "baseline" | "space-between" | "space-around" | "space-evenly"
  justifyContent?: "flex-start" | "center" | "flex-end" | "space-between" | "space-around" | "space-evenly"
  
  // Flex item
  flexGrow?: number
  flexShrink?: number
  flexBasis?: number | "auto"
  alignSelf?: "auto" | "flex-start" | "center" | "flex-end" | "stretch" | "baseline" | "space-between" | "space-around" | "space-evenly"
  
  // Size
  width?: number | "auto" | `${number}%`
  height?: number | "auto" | `${number}%`
  minWidth?: number | "auto" | `${number}%`
  minHeight?: number | "auto" | `${number}%`
  maxWidth?: number | "auto" | `${number}%`
  maxHeight?: number | "auto" | `${number}%`
  
  // Position
  position?: "static" | "relative" | "absolute"
  top?: number | "auto" | `${number}%`
  right?: number | "auto" | `${number}%`
  bottom?: number | "auto" | `${number}%`
  left?: number | "auto" | `${number}%`
  
  // Spacing
  margin?: number | "auto" | `${number}%`
  marginX?: number | "auto" | `${number}%`
  marginY?: number | "auto" | `${number}%`
  marginTop?: number | "auto" | `${number}%`
  marginRight?: number | "auto" | `${number}%`
  marginBottom?: number | "auto" | `${number}%`
  marginLeft?: number | "auto" | `${number}%`
  padding?: number | `${number}%`
  paddingX?: number | `${number}%`
  paddingY?: number | `${number}%`
  paddingTop?: number | `${number}%`
  paddingRight?: number | `${number}%`
  paddingBottom?: number | `${number}%`
  paddingLeft?: number | `${number}%`
  
  // Overflow
  overflow?: "visible" | "hidden" | "scroll"
  
  // Other
  enableLayout?: boolean
  id?: string
}

Usage Example

import { Box, Text } from "@opentui/core"

<Box
  flexDirection="row"
  alignItems="center"
  justifyContent="space-between"
  padding={10}
  width="100%"
  height={50}
>
  <Box flexGrow={1} marginRight={10}>
    <Text>Left content</Text>
  </Box>
  <Box width={100} height={30}>
    <Text>Right content</Text>
  </Box>
</Box>

Related

• Yoga Layout Documentation - Official Yoga Layout documentation
• Renderable - Base class that implements layout properties