home

Grid-based Shopify Page Editor

· 15min

I designed and built UNIGRID. It’s a Shopify app that lets merchants build their store’s pages by dragging and resizing blocks on a fixed grid, plus the custom Shopify theme those pages are published to.

It’s still WIP, but it’s pretty damn close to the editor I’ve wanted on every Shopify store I’ve worked on.

You edit the real page, every block stays exactly where you put it (on desktop or mobile), any page layout can be A/B tested without flicker, and everything is saved to Shopify metaobjects.

👉 Try the editor yourself

🤖 View repository on GitHub

Hydrogen · React Router 7 · TypeScript · Cloudflare Workers · dnd-kit · Shopify Admin & Storefront APIs


The Problem with Theme Editors

I’ve built more than 20 Shopify stores as a CRO and growth engineer, and what’s always disappointed me is that Shopify has never really had a WYSIWYG editor.

Horizon is a real step up from Dawn. You can build things with it that used to need a developer. But you still can’t pick up a block on the page and move it, or grab its edge and make it bigger…

It also gives merchants a lot of the wrong thing: a long list of block types (many of them variations on each other), and a bunch of layout sliders on every section with nothing tying them together. I think a few well-considered blocks on a strong design system would do more, especially if merchants could easily change that system themselves.

This project actually started as a Horizon build. About 30% of the way in I got bored of working around it and decided the more interesting thing was to build the editor I’d wanted all along.


Free and Fixed

The idea is free and fixed. Drag and resize any block on the page itself. Push gutters, padding and rounding as far as you like, but they’re set once for the whole theme and measured in one unit on one grid, so the page holds together.

Dragging and resizing blocks on the page. Every drop lands on whole cells.
Dragging and resizing blocks on the page. Every drop lands on whole cells.

The name comes from Massimo Vignelli, a designer I really like. “Unigrid” was his system for the US National Park Service: a handful of standard formats sharing one modular grid, with every park brochure composed on it. Hundreds of publications, one system, and none of them look the same.

That’s the part I like. A grid doesn’t limit what you can make, it makes everything you make fit together.

👉 See the full style sheet

The design system: the grid at each breakpoint, three button styles with square and rounded corners, and both heading faces.
The design system: the grid at each breakpoint, three button styles with square and rounded corners, and both heading faces.

What It Does

  • Pages are laid out by dragging blocks (text, images, products, collections, menus, cart and so on) onto a fixed grid.
  • Blocks can also be edited from the keyboard: select one, then arrow keys move it a cell at a time and Shift + arrows resize it. Cmd/Ctrl + D duplicates and Delete removes.
  • There are three breakpoints: desktop (12 columns), tablet (8) and mobile (4). Tablet and mobile are worked out from desktop, and any block can be placed by hand at either.
  • It covers home, generic pages, product and collection. Product and collection each use one template for the whole catalogue.
  • Changes save to a draft and go live on publish. Theme colours and spacing are set once and apply everywhere.
  • Any page can run an A/B test, with version B built in the same editor and picked on the server.

There are two ways in: an embedded Shopify admin app, which is the real editor and saves to the store, and a public playground running the same editor in memory.

Editing a text block in the playground. Content, alignment and size live in the sidebar.
Editing a text block in the playground. Content, alignment and size live in the sidebar.

One Scalar

Within a breakpoint the layout doesn’t reflow, it zooms.

Resizing the window. Type, spacing and blocks scale together, and nothing moves.

The whole page scales with the grid’s width, driven by one value:

.u-grid {
  --u: 1cqw;                                   /* 1% of the grid's own width */
  --gutter: calc(var(--u) * var(--gutter-u, 1.5));
  --col: calc((100cqw - (var(--cols) - 1) * var(--gutter)) / var(--cols));
  --row: calc(var(--col) * 0.75);              /* cells keep one shape */
  grid-template-columns: repeat(var(--cols), minmax(0, 1fr));
  grid-auto-rows: var(--row);
}

Gutters, type, padding and corner radii are all multiples of --u, and there are no pixel values in the grid. Because --u is based on the grid’s own width rather than the window, the editor can preview a phone just by narrowing the canvas. Theme settings are stored as multiples of --u too, so a merchant’s gutter scales with everything else.

The grid overlaid on a real page, with theme settings measured in grid units.
The grid overlaid on a real page, with theme settings measured in grid units.

The Layout Engine

Most of the work (and nearly all of the mistakes) went into the layout engine. It had to stop you breaking a page and still do exactly what you dragged.

The engine is about 1,500 lines of TypeScript with no dependencies, and lint rules that stop it importing React, Shopify, the router or the DOM. I built and tested it before anything was draggable.

The Model

A block is a box with a size and some content. Its type decides what it renders and nothing else, so every block follows the same placement rules.

type Cell = {col: number; colSpan: number; row: number; rowSpan: number};

// presence is the override flag, so a derived placement can never go stale
type Placement = {a: Cell} & Partial<Record<'b' | 'c', Cell>>;

Desktop (a) is always set. If tablet (b) or mobile (c) has a cell, the block was placed by hand at that breakpoint, and if not, its position is worked out. There’s no separate “overridden” flag that could get out of sync, and resetting a block just deletes its cell.

Every Edit Is Checked First

Every move, whether it’s a drag or an arrow key, is checked before it’s applied, and the check returns either the new layout or the reason it was refused:

type Invalid =
  | {ok: false; reason: 'out-of-bounds'}
  | {ok: false; reason: 'bad-span'}
  | {ok: false; reason: 'overlap'; with: string}
  | {ok: false; reason: 'no-such-block'};

function place(layout, id, band, cell): {ok: true; value: Layout} | Invalid

The main rule is that no edit moves a block other than the one you’re editing. A drop that would overlap something or fall off the grid is refused, never fixed by shoving a neighbour aside.

The one exception is add row, which moves everything below a line down together, because that’s what you asked for. Duplicate uses it too, opening up empty rows below the original so the copy can’t land on anything.

// a block crossing the line stays put, so no span changes and nothing can land on anything else
export const insertRow = (layout: Layout, row: number, count = 1): Layout => ({
  ...layout,
  blocks: layout.blocks.map((b) =>
    b.at.a.row >= row ? {...b, at: {...b.at, a: {...b.at.a, row: b.at.a.row + count}}} : b,
  ),
});

Every engine function returns a new layout rather than changing the old one, so undo is just a list of past layouts to step back through.


The Part I Got Wrong

For the first four phases, blocks grew to fit their content. The engine measured text in the browser and, when copy didn’t fit, added rows and pushed down whatever was below. A strict grid that still made room for real content seemed like the best of both.

In practice it fought me the whole way. Blocks crept a row taller on every edit, because the browser measures in whole pixels and grid rows aren’t whole pixels. The editor saved grown sizes as if the merchant had chosen them. Each fix turned up the next problem.

The masthead ended it. Its heading needed three rows but was set to two, so it had grown by one. Dragging its bottom edge up did nothing to it and moved everything underneath instead. Sliding it sideways pushed an unrelated block down, just because they now shared a column. All of it matched the spec, and none of it made sense to someone looking at what they’d just dragged.

So I deleted it. Blocks are now exactly the size you set, anything extra is cut off, and the editor flags blocks that are cutting content. More code came out than the feature had added, and text blocks now follow the same placement rules as every other block.


Working Out Smaller Screens

Tablet and mobile are worked out from the desktop reading order (row, then column), laid into a fixed number of tracks:

export const COLUMNS = {a: 12, b: 8, c: 4};
export const TRACKS  = {a: 1,  b: 2, c: 1};   // tablet pairs up, mobile stacks

Blocks wider than half the desktop grid stay full width. Everything else goes into whichever track has room highest up. A block placed by hand only takes up its own columns, so pinning one on mobile doesn’t leave dead space beside it:

// step past anything hand-placed in these columns rather than reserve the whole row for it
const settle = (col: number, from: number): number => {
  let row = from;
  for (;;) {
    const clash = fixed.find((f) => overlaps({col, colSpan, row, rowSpan}, f));
    if (!clash) return row;
    row = clash.row + clash.rowSpan;
  }
};

This took two goes. The first version stacked everything full width on both tablet and mobile, so tablet was really just mobile, bigger. I considered shrinking desktop sizes by 8/12 instead, but that means rounding to whole columns and then fixing the overlaps the rounding causes (and 3 columns of 12 doesn’t look the same as 2 of 8, even though it’s the same proportion). Two side by side is simpler to build and simpler to explain.


Architecture

core/        grid maths, block model, derivation, serialisation, undo
             zero dependencies: no React, no Shopify, no DOM
blocks/      block renderers and the grid CSS, shared by both apps
editor/      the editing UI: drag (dnd-kit), selection, inspector
storefront/  Hydrogen on Cloudflare Workers. Read only.
admin-app/   embedded Shopify app. The only thing that writes.

One grid everywhere. The storefront and admin app have to render the same grid, so the blocks live in a shared package. The admin app isn’t a Hydrogen app, so Hydrogen’s <Image> and links are passed in by whichever app is hosting them, with plain HTML as the fallback:

const Ctx = createContext<ImageRender>(Img);       // plain <img> by default

// storefront: a thin wrapper over Hydrogen's <Image>
<Grid image={StoreImage} link={StoreLink}>…</Grid>

The storefront can’t write. A save route on the storefront would have been a public, unauthenticated way to change the store. Instead the editor runs in two shells, and the difference is one optional prop:

<Editor initial={playground} />                        // public: no save button, no save path
<Editor initial={fromStore} onSave={saveDraft} />      // admin app

The playground can’t save because it isn’t given anything to save with.

No iframe. Theme editors usually show the store in an iframe, and dragging from a sidebar into an iframe is awkward. The editor renders the real blocks on the same page instead.

Cloudflare, not Oxygen. Shopify’s own host only gives you a public URL on a paid plan. It runs on the same runtime as Cloudflare Workers, so moving was mostly a deploy change. I ruled out Vercel because it lacks the caching API Hydrogen uses for Shopify queries.


Saving to Shopify

Layouts are stored in Shopify metaobjects, written by the admin app and read by the storefront. Shopify caps JSON fields at 128KB, so the saved format uses short keys, leaves out defaults, and doesn’t store anything that can be worked out:

{v, b:[block]}
block = {i, a:cell, b?:cell, c?:cell, f?:fill, k?:[node]}
cell  = [col, row] | [col, row, colSpan] | [col, row, colSpan, rowSpan]

An empty block saves as {"i":"x","a":[1,1]}, and a realistic homepage comes out at 10–22KB.

  • Blocks store references, not data. A product block holds a product handle. On the product template, “whichever product this page is for” is saved as nothing at all, so a template can’t get stuck on the product it was previewed with.
  • Draft and published are separate. Publish copies the saved draft, not what’s on screen, so unsaved edits can’t go live.
  • Colours are palette slots, not hex values. Changing a theme colour recolours every page without touching a layout.
A collection block showing real Shopify products. Mobile only offers column counts that divide the desktop one.
A collection block showing real Shopify products. Mobile only offers column counts that divide the desktop one.

Testing the Engine

The engine is tested with Vitest, in plain Node, with no browser and no Shopify. That’s only possible because core/ has no dependencies: every function takes a layout and returns a new one, so a test can call it directly.

The test I value most generates 25,000 random, crowded layouts and checks that no two blocks overlap at any breakpoint. There’s no property-testing library behind it, just a small random number generator that takes a seed. Each layout is 4 to 18 blocks packed tightly on the desktop grid, because crowded layouts are where working out tablet and mobile is most likely to put two blocks on top of each other:

for (let seed = 0; seed < 25_000; seed++) {
  const r = rng(seed);                           // same seed, same layout, every run
  const layout = densePacked(r, int(r, 4, 18));  // 4–18 blocks, packed tight

  for (const band of BANDS) {
    const cells = [...derive(layout, band).values()];
    for (let i = 0; i < cells.length; i++)
      for (let j = i + 1; j < cells.length; j++)
        if (overlaps(cells[i], cells[j])) throw new Error(`seed ${seed} band ${band}`);
  }
}

That’s over 750,000 positions checked per run, in under half a second. If it ever fails, the error names the seed and breakpoint, so that one layout can be rebuilt and debugged on its own. Each generated desktop layout is also checked before anything is worked out from it, so a bug in the generator can’t pass for a bug in the engine.

Smaller tests check that drops land on whole cells, saving and loading loses nothing, undo then redo gets back the same state, and an edit changes only the block being edited.

The save and publish code only depends on the few Shopify methods it actually calls, so a small fake stands in for Shopify and the whole write path is tested without a network. Playwright takes a screenshot at each breakpoint and fails if the grid changes.


A/B Testing

On every store I’ve worked on, A/B tests ran in a separate tool that loads after the page and rewrites it in the browser. That means flicker, and a second place to build the variant, away from the page it’s testing. So I built PostHog feature flags (my favourite tool) right into the editor.

The A/B section in the editor, and version B saved to the page&#x27;s metaobject as Published B.
The A/B section in the editor, and version B saved to the page's metaobject as Published B.

Whole Pages, Not Blocks

Hiding a block per variant seemed obvious, but the engine never closes gaps, so a hidden block just leaves a hole. Moving blocks per variant would mean checking every variant for overlaps at every breakpoint.

So a variant is a whole layout for one page. That’s already what the merchant builds, B gets its own tablet and mobile layouts the same way A does, and the engine doesn’t need to know a test is running. I kept it to two versions, since most stores struggle to fill two with traffic, let alone three.

PostHog Owns the Split, Shopify Owns the Content

The merchant enters a PostHog flag key. PostHog already handles the split, pausing and rollout, so storing any of that in Shopify would mean two places that could disagree. The page’s metaobject only stores the content and which flag to use:

draft, published          A, as before
draft_b, published_b      B
flag                      the PostHog flag key

A test only runs when B is published, a flag is set and the flag is on in PostHog. Otherwise everyone sees A, which also covers a mistyped key.

The matching flag in PostHog, with a 50/50 split between control (A) and test (B).
The matching flag in PostHog, with a 50/50 split between control (A) and test (B).

No Flicker, Because the Browser Never Decides

Here the choice is made on Cloudflare before the page is built, so the browser only ever gets one version. Hydrogen’s server code is the Cloudflare worker, and the page’s loader asks which version this visitor gets before anything renders:

const flag = region.fields.find((f) => f.key === 'flag')?.value;
const b = layoutFrom(region, 'published_b');
if (!b || !isFlag(flag)) return {body: a};

const {arm, counted} = await ab.arm(flag);

A cookie remembers the answer, so PostHog is only asked on a visitor’s first view, and it gets 300ms to reply. If it’s slow, the visitor sees A and isn’t counted, so a slow PostHog can’t slow the page or skew the results. Flagged pages aren’t cached, and ?ug_arm=b previews either version without being counted.

What keeps it flicker-free is that no component reads the flag. Components run again in the browser, so a flag read inside one would be decided there too.

In the Editor

The sidebar gets an A/B section: create a test (B starts as a copy of A), toggle between versions, and enter the flag key. Each version keeps its own undo history, and publish puts both live together. The test ends with Roll out on the winner, which ships the version that was tested, not anything changed since. It’s the one thing undo can’t reverse, so it asks first.

Still to build: sending exposure events from the browser, and linking orders to a version through a cart attribute.


Known Limits

Type is sized relative to the grid, so it doesn’t respond to browser zoom or a user’s font-size setting. That fails WCAG 1.4.4, and I’ve accepted it for now. Because every size comes from --u, I expect the fix to be one clamp() with a minimum size, not a change to the layout.


Key Learnings

Use it by hand as early as possible. Growing blocks passed every test I wrote, and it took dragging a real masthead to see they were wrong.

Make broken states hard to create. Bad drops are refused rather than undone, and controls only offer values that work.

Keep the core free of everything else. Because the engine imports nothing, it runs 25,000 layouts in plain Node in under a second, and the editor and storefront share it unchanged.

UNIGRID ended up as a layout engine first and an editor second. Because a layout is just checked data, it can be saved, previewed and A/B tested without much risk of breaking anything.

Read my growth & design notes

Start reading
Growth notes