Introduction, Structure & Import Workflow

Alus Builder stores every page layout as a JSON Schema. When you drag-drop on the canvas, the builder composes JSON behind the scenes. You can also write JSON yourself (Notepad, VS Code, or via Claude/ChatGPT) and Import it — instant layout.

Use cases

• AI-generated layouts: prompt ChatGPT/Claude → JSON → paste. Faster than manual drag-drop.
• Template sharing: copy JSON across pages or sites — global classes travel with it.
• Bulk edit: find-replace 50 text/color instances at once.
• Version control: store JSON in Git to track layout changes.
• Backup: export before big experiments, import back to roll back.

Root: BuilderSchema

{
  "elements": [
    /* AlusElement[] here */
  ]
}

Only 1 required field: elements (array of AlusElement). Versioning lives on the Flat Alus File envelope (version, auto-filled from the latest published Alusio changelog at Export time — see below).

AlusElement — common shape

Every element shares the same outer shape — only props varies:

{
  // ── REQUIRED ──
  "id": string,            // 8-char unique, e.g. "0jv1rmtf"
  "type": string,          // discriminator: "heading" | "button" | "section" | ...
  "props": object,         // type-specific (see element pages)

  // ── OPTIONAL ──
  "label": string,         // custom label in Structure panel
  "classes": string[],     // shortIds referring to globalClasses
  "style": {               // responsive styling
    "desktop": { ... },
    "tablet": { ... },
    "mobile": { ... },
    "selectorStyles": [ ... ]
  },
  "displayConditions": { ... },
  "interactions": [ ... ],
  "animation": { ... },

  // ── LAYOUT TYPES ONLY ──
  "children": AlusElement[]
}

id — single short ID

8-char alphanumeric, no prefix in JSON. The renderer auto-prefixes alsbldr- for DOM/CSS:

// JSON:  { "id": "0jv1rmtf", ... }
// DOM:   <div id="alsbldr-0jv1rmtf">
// CSS:   #alsbldr-0jv1rmtf { ... }

IDs must be unique across the whole schema (not just within a parent). The validator rejects duplicates.

type

Basic Element category: heading, basicText, richText, button, textLink, image, video, icon. Layout wrappers: section, container, block. Full per-category list lives on the individual element pages.

classes — global class refs

Array of shortIds referring to entries in the file's globalClasses array, or to the site's DB pool. See the Global Classes page for details.

style — responsive

"style": {
  "desktop": { "fontSize": "64px", "fontWeight": "800", "color": "#0f172a" },
  "tablet":  { "fontSize": "48px" },
  "mobile":  { "fontSize": "32px" }
}

Standard CSS props: fontSize, fontWeight, color, backgroundColor, padding, margin, textAlign, width, maxWidth, borderRadius, display, flexDirection, justifyContent, alignItems, gap. Omit style entirely to keep the theme defaults.

children — layout-only

Required for: section, container, block, sidebarLayout (+ sidebarMain, sidebarAside), tabs (+ tab), twoColLayout (+ col1, col2). Empty [] is OK. Forbidden on leaf types.

Minimal valid schema

{
  "elements": [
    {
      "id": "sec001x9",
      "type": "section",
      "props": {},
      "children": [
        {
          "id": "con002y8",
          "type": "container",
          "props": {},
          "children": [
            {
              "id": "h003z7w6",
              "type": "heading",
              "props": { "text": "Hello World", "level": "h1", "alignment": "center" }
            }
          ]
        }
      ]
    }
  ]
}

Standard hierarchy: section > container > elements. Section is a full-width wrapper, container caps the max-width. props: {} on section/container is valid (the layout schema has internal defaults).

How to Import JSON

1. Open the builder editor: /dashboard/[siteSlug]/pages/[pageId]/builder
2. In the right panel (Structure), click the menu (⋯) button
3. Click Import Schema
4. Modal opens → paste JSON (or click Choose JSON File to upload .json)
5. Pick a mode:
   • Replace all — current schema is overwritten
   • Append — new elements appended to existing layout
6. Click Import. If there's a global class conflict, a per-class modal lets you pick skip / replace / rename.
7. Click Save in the topbar to persist.

How to Export JSON

Two export options — both produce the same flat self-describing format:

• Copy All (Structure → menu ⋯ → Copy All) — JSON to clipboard. Great for pasting into ChatGPT/Claude to edit, then back via Import.
• Export File (Structure → menu ⋯ → Export) — downloads a .json file for backup or Git.

Output:

{
  "source": "alusioCopiedElements",
  "version": "1.4.0",
  "exportedAt": "2026-05-09T10:00:00.000Z",
  "sourceUrl": "https://your-site.alusio.com",
  "elements": [...],
  "globalClasses": [...]
}

Four accepted JSON shapes

Import is smart — accepts 4 input shapes, auto-normalizes:

1. Flat Alus File (the main Export format) — see above.
2. Raw BuilderSchema (recommended for hand-craft & AI):

   { "elements": [...] }

3. Elements array (paste several elements at once):

   [
     { "id": "0jv1rmtf", "type": "heading", "props": {...} },
     { "id": "btn001ax", "type": "button", "props": {...} }
   ]

   Builder auto-wraps.
4. Single element snippet (paste just one):

   {
     "id": "0jv1rmtf",
     "type": "heading",
     "props": { "text": "Hello", "level": "h1", "alignment": "center" }
   }

   Builder auto-wraps it.

This means JSON examples on the next pages can be imported as-is — no manual wrapping.

Validation before Import

After auto-wrap, the builder validates the schema. Ensure:

• Every element has id (unique string across the whole schema), type (valid AlusElementType), props (object — empty {} OK).
• Layout elements (section, container, block, etc.) must have a children array — empty is OK.
• Leaf elements (heading, button, image, etc.) must not have children.
• ID format: 8-char alphanumeric (e.g. 0jv1rmtf). Free-form as long as unique. The renderer auto-prefixes alsbldr- for DOM/CSS output.

If JSON fails, you get a specific error message (which field is invalid + path).