Constraints API Reference

Rezi supports constraint-driven layout via expr("...") and a helper-first API layer that generates constraint expressions for common patterns.

This page documents the public helper layer exported from:

• @rezi-ui/core
• @rezi-ui/jsx (re-exports for parity)

See also:

• docs/guide/constraints.md
• docs/reference/constraint-expressions.md

expr(source)

expr("...") parses a constraint DSL string and returns a frozen ConstraintExpr object.

Use it when:

• You need a layout relationship that isn’t covered by helpers
• You’re prototyping, or translating an existing expression from docs/tests

Prefer helpers for day-to-day usage so app code reads like layout intent.

Helper namespaces

All helpers:

• Return ConstraintExpr
• Validate arguments and throw ConstraintHelperError with a clear message
• Preserve solver semantics by compiling to expr("...") (no implicit fallbacks)

visibilityConstraints.*

For display: ... rules (layout/viewport-driven visibility).

• viewportWidthAtLeast(cols: number)
• viewportWidthBelow(cols: number)
• viewportHeightAtLeast(rows: number)
• viewportHeightBelow(rows: number)
• viewportAtLeast(options: { width?: number; height?: number })

Examples:

ui.box({ display: visibilityConstraints.viewportWidthAtLeast(80) }, [...])
ui.box({ display: visibilityConstraints.viewportAtLeast({ width: 110, height: 28 }) }, [...])

conditionalConstraints.*

Intent wrapper for conditional sizing.

• ifThenElse(cond: number | ConstraintExpr, thenValue: number | ConstraintExpr, elseValue: number | ConstraintExpr)

Example:

width: conditionalConstraints.ifThenElse(
  visibilityConstraints.viewportWidthAtLeast(120),
  60,
  100,
)

widthConstraints.*

Common width sizing patterns.

• percentOfParent(ratio: number) → parent.w * ratio
• percentOfViewport(ratio: number) → viewport.w * ratio
• clampedPercentOfParent({ ratio, min, max }) → clamp(min, parent.w * ratio, max)
• clampedViewportMinus({ minus, min, max }) → clamp(min, viewport.w - minus, max)
• minViewportPercent({ ratio, min }) → max(min, viewport.w * ratio)
• stepsByViewportWidth({ steps }) → steps(viewport.w, t1: v1, t2: v2, ...)
• clampedIntrinsicPlus({ pad, min, max?: number | "parent" }) → clamp(min, intrinsic.w + pad, parent.w|max)

heightConstraints.*

Height analogs of widthConstraints.

• percentOfParent(ratio: number)
• percentOfViewport(ratio: number)
• minViewportPercent({ ratio, min }) → max(min, viewport.h * ratio)
• clampedPercentOfParent({ ratio, min, max })
• clampedPercentOfViewport({ ratio, min, max })
• clampedViewportMinus({ minus, min, max })
• stepsByViewportHeight({ steps }) → steps(viewport.h, t1: v1, t2: v2, ...)
• clampedIntrinsicPlus({ pad, min, max?: number | "parent" })

groupConstraints.*

Sibling aggregation wrappers (equalization / totals).

These are most useful when multiple siblings under the same parent share the same non-interactive id (for example repeated label widgets), and you want a max/sum across that local group.

• maxSiblingWidth(id: string) → max_sibling(#id.w)
• maxSiblingHeight(id: string) → max_sibling(#id.h)
• maxSiblingMinWidth(id: string) → max_sibling(#id.min_w)
• maxSiblingMinHeight(id: string) → max_sibling(#id.min_h)
• sumSiblingWidth(id: string) → sum_sibling(#id.w)
• sumSiblingHeight(id: string) → sum_sibling(#id.h)
• sumSiblingMinWidth(id: string) → sum_sibling(#id.min_w)
• sumSiblingMinHeight(id: string) → sum_sibling(#id.min_h)

Example:

ui.row({ gap: 2 }, [
  ui.box(
    { id: "kv-key", width: groupConstraints.maxSiblingMinWidth("kv-key"), border: "none", p: 0 },
    [ui.text("Latency", { dim: true })],
  ),
  ui.text("12ms"),
])

spaceConstraints.*

“Derived remaining space” helpers (make intent explicit, avoid manual math).

• remainingWidth({ subtract, minus?, clampMin? })
• remainingHeight({ subtract, minus?, clampMin? })

subtract terms:

type SpaceTerm = { id: string; metric?: "width" | "height" | "minWidth" | "minHeight"; aggregation?: "none" | "max" | "sum" }

Example:

ui.row({}, [
  ui.box({ id: "sidebar", width: 24 }, [...]),
  ui.box({ id: "main", width: spaceConstraints.remainingWidth({ subtract: [{ id: "sidebar" }], minus: 1 }) }, [...]),
])