← ConceptsResponsive designOne Layout JSON should not look the same on a 5-inch phone, an 11-inch tablet, and a split-screen iPad. The `responsive` block lets a single component swap attribute values per size class or window width — without forking the layout file. Here is how the resolver picks the one set of values that wins, what the generator emits per platform, when responsive is the wrong tool — and the `home@regular.json` variant files that swap the whole tree when it is.~7 min read
The problemA vertical stack with 8 px spacing reads fine on a phone, but on an iPad in landscape the same stack feels cramped — the screen has the room to lay sections out horizontally with 24 px spacing. When only attribute values differ, forking the whole file into `home.json` and `home@regular.json` doubles the maintenance cost for a spacing tweak; doing all the math at the ViewModel layer leaks layout concerns into business code. The `responsive` block is the third option: keep one Layout JSON, declare the deltas, let the runtime pick. (When the structure itself changes per size class, the whole-file fork IS the right tool — that is the variant-file mechanism covered below.)
Seven size-class keysThe resolver recognizes a fixed set of keys. Each maps to a host-platform predicate that the runtime evaluates on every layout pass.• `compact` — narrow width. iPhone portrait, foldable inner display closed, web < 768 px.• `medium` — tablet portrait, split-screen iPad, web ≈ 768–1023 px. iOS has no native medium class — falls back to `compact`.• `regular` — wide width. iPad landscape full-screen, web ≥ 1024 px.• `landscape` — the window is wider than it is tall, whatever its width class. Web reads the `(orientation: landscape)` media query and Android compares `LocalWindowInfo.containerSize`; iOS uses a compact vertical size class — an iPhone turned sideways, not a full-screen iPad.• `compact-landscape` / `medium-landscape` / `regular-landscape` — composite keys. Match only when BOTH conditions hold; rank above the single keys in the priority table. iOS has no medium width, so there `medium-landscape` holds where `compact-landscape` does.
The `responsive` blockDrop a `responsive` object next to the base attributes. Keys are size-class names (or window-width conditions, below); values are partial attribute objects that override the base when the host matches that key. The base attributes are the default — used when no key matches.
layout.json
{ "type": "View", "orientation": "vertical", "spacing": 8, "responsive": { "regular": { "orientation": "horizontal", "spacing": 24 }, "landscape": { "spacing": 16 }, "regular-landscape": { "orientation": "horizontal", "spacing": 32 } }, "child": [ /* … */ ]}Resolution prioritySeveral keys can hold at once — a 1200 × 800 browser window is `regular`, `landscape` AND `regular-landscape`. The resolver does not stack them. It takes the keys in priority order — `regular-landscape` > `medium-landscape` > `compact-landscape` > `landscape` > `regular` > `medium` > `compact` — and the first one that is in the block and holds wins alone: only its overrides go onto the base, and every other key contributes nothing, even for attributes the winner does not set. When no key holds, the base is drawn as written. Generated code on all three platforms and both Dynamic runtimes resolve the same way.
resolution.txt
// One key wins, alone. Priority, highest first:// regular-landscape > medium-landscape > compact-landscape// > landscape > regular > medium > compact > base (no key)//// Only the winner's overrides go onto the base; the other keys add nothing.// Given the JSON above (browser window sizes in CSS px):// 1200 x 800 (regular, landscape) -> regular-landscape wins// orientation: "horizontal" <- regular-landscape// spacing: 32 <- regular-landscape// 1200 x 1400 (regular, portrait) -> regular wins// orientation: "horizontal" <- regular// spacing: 24 <- regular// 700 x 400 (compact, landscape) -> landscape wins// orientation: "vertical" <- base (landscape does not set it)// spacing: 16 <- landscape// 390 x 844 (compact, portrait) -> no key holds// orientation: "vertical" <- base// spacing: 8 <- base//// Without "regular-landscape" in the block, 1200 x 800 goes to landscape// alone: orientation "vertical" from the base, not regular's "horizontal".Window-width conditions — `minWidth:N` / `maxWidth:N`When the breakpoints you need are not the size classes' (768 / 1024 px on the web, 600 / 840 dp on Android, the horizontal size class on iOS), key the block by the window's width instead. `minWidth:N` holds when the window is at least N wide; `maxWidth:N` when it is narrower than N — N itself is not included, so `maxWidth:600` and `minWidth:600` split the widths with no gap and no overlap. N is a whole number in the platform's logical unit (iOS pt, Android dp, web CSS px), and the width is the window's, not the parent view's. It also works in Dynamic mode.• One condition wins, alone, as a size class does: the smallest `maxWidth` that holds, else the largest `minWidth`. At 1300 wide, `minWidth:600` and `minWidth:1200` both hold and `minWidth:1200` wins.• `jui build` refuses with `ERROR [responsive]` a block that mixes width conditions with size classes, a landscape combination such as `minWidth:700-landscape`, a unit or a fraction in N, and a `maxWidth` whose N is above a `minWidth`'s — so a `maxWidth` and a `minWidth` never hold at once.• Where the width comes from: iOS reads the scene's width (`SJUIWindowWidth`), Android `LocalWindowInfo.containerSize` in dp, and the web the viewport, through `min-[Npx]:` / `max-[Npx]:` classes scoped to the range in which each condition wins.• Not the same `maxWidth` as jsonui-test-runner's: a test's responsive condition reads `maxWidth` as "at most N"; a layout key's means "less than N".
layout.json
// below 600: 1 column · 600–1199: 2 columns · 1200 and up: 4 columns{ "type": "Collection", "columnCount": 1, "responsive": { "minWidth:600": { "columnCount": 2 }, "minWidth:1200": { "columnCount": 4 } }}Generated mode: wrapper functionsIn generated mode each platform's converter inlines the resolution at compile time, one branch per key in priority order, so only the winner's values are drawn. SwiftUI lifts the responsive container into a `@ViewBuilder` helper to keep type-checker work bounded; the children are emitted once and threaded through `content()`, so an inner `Collection` or `Label` is not duplicated per branch. Compose emits the `if` / `else` chain inline at the call site — no `@Composable` wrapper — so each branch stays in the caller's `Row` / `Column` / `Box` scope and reads the screen's `data` and `viewModel` directly. React draws a block of size classes with breakpoint classes whose ranges do not overlap (`md:max-lg:` for medium); a block with a landscape key gives each key media variants for the windows where it is the winner (`landscape:` / `portrait:` with the width bands), which come after the base classes, so the winner always wins. On web a size class's other keys are drawn when the override only adds classes (a Collection's columns and spacings, a border's colour, width and style, borderWidth 0 to take a border away, the relative align and center keys); a key it cannot carry — an offset, an override that is itself a binding, one that would take a base class away or change an inline style or the markup — is a `jui build` WARNING that names the node, the size class, the key and why.
Generated.swift
// SwiftUI — the converter lifts the responsive container into a// @ViewBuilder helper, then injects the children via `content()`.// Children are emitted ONCE; only the wrapper branches.@ViewBuilder private func responsiveContentArea<Content: View>( @ViewBuilder content: () -> Content) -> some View { if horizontalSizeClass == .regular { HStack(spacing: 24) { content() } } else { VStack(spacing: 8) { content() } }} var body: some View { responsiveContentArea { section0_0() section0_1() }}Generated.kt
// Compose — an inline if / else chain at the call site, one branch per key// in priority order. No wrapper function: the branch sits in the caller's// Row / Column / Box scope and reads data / viewModel directly.if (with(LocalDensity.current) { LocalWindowInfo.current.containerSize.width.toDp().value.toInt() } >= 840) { Row(horizontalArrangement = Arrangement.spacedBy(24.dp)) { // children }} else { Column(verticalArrangement = Arrangement.spacedBy(8.dp)) { // children }}Generated.tsx
{/* React — the JSON from the priority section. Each key is a set of media variants for the windows where it is the winner: portrait: / landscape: with the width bands (lg: is 1024px and wider, max-lg: narrower). Tailwind writes variant classes after the plain ones, so the winner always wins over the base. A block of size classes alone uses breakpoint classes (`lg:` for regular, `md:max-lg:` for medium). */}<div className="flex flex-col portrait:lg:flex-row portrait:lg:gap-[1.5rem] landscape:max-lg:gap-[1rem] landscape:lg:flex-row landscape:lg:gap-[2rem] gap-[0.5rem]" />Dynamic mode: tree resolutionDynamic mode (the runtime that powers hot reload on iOS and Android) takes a different path. A shared `ResponsiveResolver` walks the JSON tree once at mount time, flattens every node by merging the winning `responsive` key back into the parent, and hands a plain JSON dictionary to the per-component converter. Individual converters never know `responsive` exists — they see the resolved attributes only. SwiftJsonUI keys off `@Environment(\.horizontalSizeClass)` and `verticalSizeClass`, and reads window-width conditions from `SJUIWindowWidth` (the scene's width in points); KotlinJsonUI uses the window's `WindowSizeClass` for the width class and `LocalWindowInfo.containerSize` for orientation and for width conditions (in dp). Both rely on the platform's own change-tracking to re-run resolution when the host rotates or splits.
Variant files — `home@regular.json`When the structure itself must change per size class, ship a whole alternative tree instead of overrides: keep `home.json` as the canonical base and place `home@compact.json` / `home@medium.json` / `home@regular.json` next to it. Those three suffixes are the entire vocabulary — landscape and composite keys remain inline-`responsive` territory, and `@tablet` is rejected with a dedicated "did you mean '@regular'?" hint. Resolution is exact-match or base, never a neighboring tier: a medium window with only `@regular` shipped renders the base, and iOS — which has no medium size class — folds `@medium` into its compact tier with `@compact` winning. Tier detection is identical to the inline `responsive` block (iOS horizontal size class, Android 600 / 840 dp, web 768 / 1024 px).Variants declare no `data` and no `platforms` — the data contract stays base-canonical: every binding a variant uses must be declared in the base, ViewModel / Data / spec are generated from the base alone, and `jui build` enforces all of it (vocabulary, orphan variants, `data` / `platforms` declarations, uncovered bindings) as hard errors. Because a tier change swaps the WHOLE tree, view-local state (scroll position, unbound input, focus) is lost by design while the single ViewModel instance — and every bound value — survives: state that must outlive a Split View / foldable transition belongs in a VM binding. In generated mode each variant compiles to its own `<Base><Class>VariantGeneratedView` sharing the base's Data / ViewModel; dynamic mode reads the `@` files as well.
variant resolution
Layouts/├── home.json ← canonical base (data section lives here)├── home@compact.json ← optional whole-tree swap, compact tier└── home@regular.json ← optional whole-tree swap, regular tier // tier → file: exact match or base — no promotion between tiers// regular window → home@regular.json// medium window (no @medium shipped) → home.json// iOS (no medium class): @medium folds into compact; @compact winsWhen `responsive` is not the right toolThree nearby tools can all answer 'this should look different here'. They are not interchangeable.`responsive` — same component, different attribute valuesUse when the structure stays identical across size classes — same children in the same order — and only spacing, orientation, font size, column count, or similar attribute values need to flip.`platform` — omit or override per hostUse when a subtree is platform-specific — an iOS-only screenshot, a web-only sidebar, an Android-only system-bar inset filler. Give the node a string `platform` (`"platform": "ios"`, comma lists like `"ios,android"` too) and `jui build` drops it entirely on the other hosts. For per-host attribute values on a shared node, use the object form instead: `"platform": {"ios": {"height": 220}, "web": {"height": "100vh"}}`. (A `platforms` ARRAY is valid only on the layout root, where it whitelists which platforms the whole screen ships to.)Variant file (`home@regular.json`) — different structure entirelyWhen the children themselves change — phone shows a stack of cards, tablet shows a master-detail layout — `responsive` is the wrong shape because there is no shared structure to override. Ship a variant file (`home@regular.json`) next to the canonical base instead — the runtime swaps the whole tree when the size-class tier matches. Resolution, data contract, and state rules are covered in the variant-files section above.
Keep reading
One Layout JSON, three platformsRevisit the foundational claim now that you have seen how the resolver enforces it./concepts/one-layout-json
Hot reload everywhereHow a size-class change becomes a re-render without a rebuild./concepts/hot-reload