@bedrock-core/flexbox

@bedrock-core/flexbox

Beta Status: Active development. Breaking changes may occur until 1.0.0. Pin exact versions for stability.

Flexbox layout engine for Minecraft Bedrock UI. Computes absolute texel positions and sizes for a tree of layout nodes using a CSS-compatible flexbox algorithm, targeting the Bedrock pocket screen (320×210 texels) as the canonical reference.

Installation

This package is typically installed as a dependency of @bedrock-core/ui:

yarn add @bedrock-core/ui

Or directly:

yarn add @bedrock-core/flexbox

Quick Start

import { createNode, computeLayout } from '@bedrock-core/flexbox';

// Build a layout tree
const root = createNode({
  flexDirection: 'row',
  justifyContent: 'space-between',
  alignItems: 'center',
  padding: 10,
});

const sidebar = createNode({ width: 80 });
const content = createNode({ flex: 1 });

root.children.push(sidebar, content);

// Compute layout (defaults to 320×210 pocket screen)
computeLayout(root);

// Read resolved absolute texel values
console.log(sidebar.layout); // { x, y, width, height, zIndex }
console.log(content.layout); // { x, y, width, height, zIndex }

API

createNode(style?, children?)

Create a layout node with an optional style and pre-populated children.

const node = createNode(
  { flexDirection: 'column', padding: 5 },
  [createNode({ height: 20 }), createNode({ flex: 1 })],
);

The layout field is zeroed on creation and is filled only after computeLayout() runs.

computeLayout(root, refWidth?, refHeight?)

Compute absolute texel positions and sizes for the entire tree.

// Default: pocket screen (320×210)
computeLayout(root);

// Custom reference dimensions
computeLayout(root, 376, 250); // desktop screen

After this call every node.layout holds absolute texel values:

• x, y — top-left corner from screen origin (0, 0)
• width, height — dimensions in texels
• zIndex — resolved z-order (inherits from parent when not explicitly set)

The algorithm uses a 3-pass BFS approach:

1. Pass 1 — build level-order list and parent map
2. Pass 2 (bottom-up, 3 iterations) — resolve content-driven and explicit sizes; handles percent padding convergence
3. Pass 3 (top-down) — resolve percent sizes, distribute flex grow/shrink, position children

CANONICAL_SCREEN / SCREEN

Reference screen dimensions in texels:

import { CANONICAL_SCREEN, SCREEN } from '@bedrock-core/flexbox';

SCREEN.POCKET  // { width: 320, height: 210 }
SCREEN.DESKTOP // { width: 376, height: 250 }
CANONICAL_SCREEN // same as SCREEN.POCKET

Supported Properties

Display & Positioning

Property	Type	Default	Description
display	'flex' | 'none'	'flex'	Hide node and all descendants when 'none'
position	'relative' | 'absolute'	'relative'	Absolute nodes are removed from flow

Sizing

Sizes are texels (integer) or percent strings ("50%") relative to the parent container.

Property	Type	Default	Description
width	number | Percent	auto	Explicit width
height	number | Percent	auto	Explicit height
minWidth	number | Percent	—	Minimum width constraint
maxWidth	number | Percent	—	Maximum width constraint
minHeight	number | Percent	—	Minimum height constraint
maxHeight	number | Percent	—	Maximum height constraint

Flex Container

Property	Type	Default	Description
flexDirection	'row' | 'row-reverse' | 'column' | 'column-reverse'	'column'	Main axis direction
wrap	'nowrap' | 'wrap' | 'wrap-reverse'	'nowrap'	Multi-line wrapping
justifyContent	'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly'	'flex-start'	Main axis alignment
alignItems	'flex-start' | 'flex-end' | 'center' | 'stretch'	'stretch'	Cross axis alignment
alignContent	'flex-start' | 'flex-end' | 'center' | 'stretch' | 'space-between' | 'space-around'	'stretch'	Multi-line cross axis
gap	number | Percent	0	Gap between items
rowGap	number | Percent	0	Row gap override
columnGap	number | Percent	0	Column gap override

Flex Item

Property	Type	Default	Description
flex	number	—	Shorthand for flexGrow when flexGrow is not set
flexGrow	number	0	Growth factor
flexShrink	number	1	Shrink factor
flexBasis	number | Percent | 'auto'	'auto'	Initial main size
alignSelf	'auto' | AlignItems	'auto'	Override container's alignItems

Spacing

Percent values resolve against the parent content-box width (all four sides for padding/margin). Gap percent resolves against the container's own content-box dimension on that axis.

Property	Type	Default	Description
padding	number | Percent	0	Inner spacing, all sides
paddingTop/Right/Bottom/Left	number | Percent	0	Individual padding
margin	number | Percent	0	Outer spacing, all sides
marginTop/Right/Bottom/Left	number | Percent	0	Individual margin

Absolute Positioning Offsets

Only applies when position: 'absolute'. Offsets are in texels relative to the parent.

Property	Type	Description
top	number	Distance from parent top
right	number	Distance from parent right
bottom	number	Distance from parent bottom
left	number	Distance from parent left

When both left + right are set without width, the node is stretched to fill the horizontal space. Same for top + bottom without height.

Z-order

Property	Type	Default	Description
zIndex	number	inherited	Z-order layer; inherits from parent when not set

Examples

Centered content

const root = createNode({ justifyContent: 'center', alignItems: 'center' });
root.children.push(createNode({ width: 100, height: 60 }));
computeLayout(root);

Sidebar layout

const root = createNode({ flexDirection: 'row' });
root.children.push(
  createNode({ width: 80 }),   // fixed sidebar
  createNode({ flex: 1 }),     // content fills remainder
);
computeLayout(root);

Wrapping grid

const grid = createNode({ flexDirection: 'row', wrap: 'wrap', gap: 4 });
for (let i = 0; i < 9; i++) {
  grid.children.push(createNode({ width: 100, height: 60 }));
}
computeLayout(grid);

Absolute overlay

const root = createNode({});
root.children.push(
  createNode({ flex: 1 }),                                 // normal flow
  createNode({ position: 'absolute', top: 0, right: 0, width: 40, height: 20 }), // overlay
);
computeLayout(root);

Custom screen size

import { computeLayout, SCREEN } from '@bedrock-core/flexbox';

computeLayout(root, SCREEN.DESKTOP.width, SCREEN.DESKTOP.height);

Output Format

After computeLayout(), each node exposes a layout property:

interface ComputedLayout {
  x: number;      // texels from screen left
  y: number;      // texels from screen top
  width: number;  // texels
  height: number; // texels
  zIndex: number; // resolved z-order
}

All values are rounded integers.

License

MIT