The language

Responsive design

Write the phone layout first, then add what changes as the page gets wider.

Breakpoints

NameApplies fromTypically
base0Phones (no prefix)
sm640pxLarge phones
md768pxTablets
lg1024pxLaptops
xl1280pxDesktops
2xl1536pxWide screens

A value applies from its breakpoint upwards until a larger one overrides it. base is everything below sm, and it's also the fallback for every size you don't set.

Prefixes in className

Put the breakpoint in front of any class:

Two columns on phones, three on tablets, four on laptops
<GridView className="grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4 md:gap-6">
  {products({ limit: 8 }).map((item) => (
    <Text>{item.name}</Text>
  ))}
</GridView>

Order doesn't matter (md:p-8 p-4 is the same as p-4 md:p-8), but each class takes one prefix:

ErrorUse one breakpoint prefix per class

Per-size values in props

Any prop can take an object keyed by breakpoint instead of a single value. This is what prefixes turn into, so the two are interchangeable, and the editor prints whichever reads better.

The same grid as above, written as props
<GridView crossAxisCount={{ base: 2, md: 3, lg: 4 }} mainAxisSpacing={{ base: 16, md: 24 }}>
  {products({ limit: 8 }).map((item) => (
    <Text>{item.name}</Text>
  ))}
</GridView>

Showing and hiding

hidden hides a widget; block shows it again. Combine them with prefixes to show something only from a given width:

The Details button only appears from tablet width
<Row className="justify-between items-center gap-4">
  <Text className="text-sm md:text-base">Free delivery over R500</Text>
  <TextButton className="hidden md:block" label="Details" onPressed={{ type: "page", route: "/shipping" }} />
</Row>

Phone rules

Whatever layout a page has, whether you built it, a composition laid it out or the AI wrote it, two rules keep it readable on phones:

  • Columns side by side stack. A Row with two or more Expanded or Flexible children that hold content (columns, boxes, pictures, product parts) becomes one full-width column on phones, and a row again from tablet width. On a product page the pictures come first.
  • Buttons don't get squeezed. A row with buttons, Add to Cart or a quantity picker wraps onto a new line when there isn't room, instead of squashing a button's label.

To choose for yourself, set phoneStack on the Row: always stacks it on phones, never keeps it side by side, and auto (the default) follows the rule above. It's also under On phones in the Row's properties.

Two short columns that stay side by side on phones
<Row phoneStack="never" className="items-center gap-4">
  <Expanded>
    <Column className="gap-2">
      <Text>Opening hours</Text>
      <Text>Mon–Fri 08:00–17:00</Text>
    </Column>
  </Expanded>
  <Expanded>
    <Column className="gap-2">
      <Text>Find us</Text>
      <Text>12 Vilakazi Street, Soweto</Text>
    </Column>
  </Expanded>
</Row>