Layout System

RetUI has exactly one layout component: Box.

There is no grid system, no absolute positioning to learn, and no separate Row or Column components.

Everything is built with a single Box component and a handful of layout properties.

Once you understand these properties, you can build almost any interface:

• Forms
• Dashboards
• Sidebars
• Headers
• Toolbars
• Dialogs
• Settings screens

---

The Box

Every layout starts the same way.

retui.Box(
    retui.Props{},
    retui.NewStyle(),
    // children...
)

A Box always has three parts:

1. Props – controls the layout.
2. Style – controls the appearance.
3. Children – the content inside the box.

┌────────────────────────────┐
│ Props                      │
├────────────────────────────┤
│ Style                      │
├────────────────────────────┤
│ Children                   │
└────────────────────────────┘

If you don't specify a width or height, the box automatically sizes itself to fit its content.

---

Direction

Direction controls how children are arranged.

There are only two options.

Row

Children are placed side by side.

retui.Box(
    retui.Props{
        Direction: retui.Row,
        Gap: 2,
    },
    retui.NewStyle(),

    retui.Text("Left", retui.NewStyle()),
    retui.Text("Right", retui.NewStyle()),
)

Result

Left  Right

Typical uses:

• Toolbars
• Navigation bars
• Form rows
• Header layouts

---

Column

Children are stacked vertically.

retui.Box(
    retui.Props{
        Direction: retui.Column,
    },
    retui.NewStyle(),

    retui.Text("One", retui.NewStyle()),
    retui.Text("Two", retui.NewStyle()),
    retui.Text("Three", retui.NewStyle()),
)

Result

One
Two
Three

Typical uses:

• Forms
• Menus
• Sidebars
• Dashboards

---

Nesting Layouts

Boxes can contain other boxes.

Example:

┌──────────────────────────────┐
│ Header                       │
├──────────────────────────────┤
│ Sidebar │ Main Content       │
│         │                    │
│         │                    │
├──────────────────────────────┤
│ Footer                       │
└──────────────────────────────┘

This layout is simply:

Column
 ├── Header
 ├── Row
 │    ├── Sidebar
 │    └── Content
 └── Footer

Large applications are built by nesting small layouts together.

---

Sizing

RetUI supports three sizing modes.

Fixed

A fixed size never changes.

Width: retui.Fixed(30)

Perfect for:

• Sidebars
• Labels
• Navigation menus

---

Grow

A grow size expands to fill the remaining space.

Width: retui.Grow(1)

Example

+---------+------------------------+
| Sidebar |      Main Content      |
+---------+------------------------+

The sidebar keeps its width.

The content fills everything else.

---

Grow Weights

Multiple growing boxes share space according to their weight.

Width: retui.Grow(1)
Width: retui.Grow(2)

Result

+---------+-------------------------+
|   1/3   |           2/3           |
+---------+-------------------------+

The second box receives twice as much space.

---

Fit

A fit size uses only the space required by its content.

Width: retui.Fit()

This is also the default.

---

Gap

Gap adds space between children.

Gap: 3

Result

A   B   C

Gap never adds space around the outside of the box.

It only separates its children.

---

Padding

Padding adds space inside the box.

Padding: [4]int{1,2,1,2}

Order:

Top
Right
Bottom
Left

Example

Without padding

+------------+
|Hello World |
+------------+

With padding

+--------------+
|              |
| Hello World  |
|              |
+--------------+

Padding makes components easier to read.

---

Margin

Margin adds space outside the box.

Unlike padding, margin separates one box from another.

Without margin

+-----++-----+
| One || Two |
+-----++-----+

With margin

+-----+  +-----+
| One |  | Two |
+-----+  +-----+

Use margin to separate panels, cards and sections.

---

Padding vs Margin

Margin
┌──────────────────────────┐
│ Border                   │
│ ┌──────────────────────┐ │
│ │ Padding              │ │
│ │ ┌──────────────────┐ │ │
│ │ │ Content          │ │ │
│ │ └──────────────────┘ │ │
│ └──────────────────────┘ │
└──────────────────────────┘

Padding adds space inside the border.

Margin adds space outside the border.

---

Align

Align controls how children are positioned across the cross axis.

Value	Description
AlignStart	Beginning
AlignCenter	Center
AlignEnd	End
AlignStretch	Fill available space

Example

Align: retui.AlignCenter

---

Justify

Justify controls how children are distributed along the main axis.

Value	Description
JustifyStart	Pack at the beginning
JustifyCenter	Center together
JustifyEnd	Pack at the end
JustifySpaceBetween	Equal space between children
JustifySpaceAround	Equal space around children

Example

MyApp                             v1.0.0

This layout uses

Justify: retui.JustifySpaceBetween

---

Building Complex Layouts

A complete application is simply many boxes combined together.

App
│
├── Header
├── Body
│   ├── Sidebar
│   └── Content
└── Footer

Every part of the screen is just another Box.

---

Best Practices

✅ Build layouts by nesting boxes.

✅ Prefer Grow() instead of fixed widths whenever possible.

✅ Use Fixed() only when a component should never resize.

✅ Add padding to improve readability.

✅ Use gap to separate related items.

✅ Use margin to separate sections.

✅ Keep layouts simple.

---

Quick Reference

Property	Purpose
Direction	Row or Column
Width	Fixed, Grow or Fit
Height	Fixed, Grow or Fit
Gap	Space between children
Padding	Space inside the box
Margin	Space outside the box
Align	Cross-axis alignment
Justify	Main-axis distribution

---

Summary

Every layout in RetUI is built with a single component: Box.

By combining a few simple properties—

• Direction
• Width
• Height
• Gap
• Padding
• Margin
• Align
• Justify

—you can build everything from a simple form to a full-screen dashboard without manually calculating positions.