Configuration Schema

This document provides a complete reference for the XBuilder popup configuration schema. Use this when working with exported JSON or programmatically creating popups.

Top-Level Structure

{
  "id": "string",
  "isOpen": "boolean",
  "position": "string",
  "backgroundType": "string",
  "backgroundColor": "string",
  "contentType": "string",
  "elements": [],
  "trigger": "string",
  // ... more properties
}

Core Properties

Identification

Property	Type	Description
`id`	string	Unique popup identifier
`isOpen`	boolean	Whether popup is currently open

Position

Property	Type	Values	Description
`position`	string	`center`, `top-left`, `top-center`, `top-right`, `middle-left`, `middle-center`, `middle-right`, `bottom-left`, `bottom-center`, `bottom-right`	Popup position on screen

Dimensions

Property	Type	Example	Description
`width`	string	`"500px"`, `"90%"`	Popup width
`height`	string	`"auto"`, `"400px"`	Popup height
`maxWidth`	string	`"600px"`	Maximum width
`maxHeight`	string	`"80vh"`	Maximum height
`minWidth`	string	`"300px"`	Minimum width
`minHeight`	string	`"200px"`	Minimum height

Background

Property	Type	Values	Description
`backgroundType`	string	`solid`, `gradient`, `image`	Background type
`backgroundColor`	string	`"#ffffff"`	Solid background color
`backgroundImage`	string	URL	Background image URL

Gradient Object

{
  "gradient": {
    "type": "linear",
    "direction": "180deg",
    "colors": [
      { "color": "#667eea", "position": 0 },
      { "color": "#764ba2", "position": 100 }
    ]
  }
}

Border & Shadow

Property	Type	Description
`borderRadius`	string	Corner radius (`"16px"`)
`borderWidth`	string	Border width
`borderColor`	string	Border color
`borderStyle`	string	`solid`, `dashed`, `dotted`

Box Shadow Object

{
  "boxShadow": {
    "x": "0px",
    "y": "4px",
    "blur": "20px",
    "spread": "0px",
    "color": "rgba(0,0,0,0.15)"
  }
}

Content

Property	Type	Description
`contentType`	string	`elements` (always for visual builder)
`elements`	array	Array of element objects

Overlay

Property	Type	Description
`overlayColor`	string	Overlay background color
`overlayOpacity`	number	Opacity 0-1
`overlayBlur`	string	Backdrop blur amount
`closeOnOverlayClick`	boolean	Close when clicking overlay

Close Button

Property	Type	Description
`showCloseButton`	boolean	Show/hide close button
`closeButtonPosition`	string	`inside-top-right`, `outside-top-right`
`closeButtonSize`	string	Button size
`closeButtonColor`	string	Icon color

Animation

Property	Type	Description
`animation`	string	Entry animation name
`exitAnimation`	string	Exit animation name
`animationDuration`	string	Animation duration (`"300ms"`)

Trigger Properties

Property	Type	Values	Description
`trigger`	string	`onload`, `onclick`, `onscroll`, `onexit`, `timed`, `floatingbutton`	Trigger type
`triggerDelay`	number	Milliseconds	Delay before showing
`triggerScroll`	number	0-100	Scroll percentage
`triggerSelector`	string	CSS selector	Click trigger selector

Property	Type	Description
`cookieType`	number	Cookie type identifier
`cookieDuration`	number	Days until cookie expires
`cookieSetTiming`	string	`afterClose`, `afterDisplay`
`testMode`	boolean	Ignore cookies when true

Element Schema

Each element in the elements array follows this structure:

{
  "id": "string",
  "type": "string",
  "order": "number",
  "content": {},
  "style": {},
  "advanced": {},
  "children": []
}

Element Identification

Property	Type	Description
`id`	string	Unique element ID
`type`	string	Element type
`order`	number	Display order

Element Types

Type	Description
`text`	Text paragraph
`heading`	Heading (h1-h6)
`button`	Clickable button
`image`	Image display
`video`	Video embed
`icon`	Font Awesome icon
`divider`	Horizontal line
`spacer`	Empty space
`maps`	Google Maps embed
`iframe`	External iframe
`section`	Row container
`column`	Column container

Content Object

Content varies by element type:

Text/Heading

{
  "content": {
    "text": "Your text here",
    "alignment": "center"
  }
}

Button

{
  "content": {
    "text": "Click Me",
    "link": "https://example.com",
    "target": "_blank",
    "action": "link"
  }
}

Image

{
  "content": {
    "src": "https://example.com/image.jpg",
    "alt": "Image description",
    "link": "",
    "width": "100%",
    "height": "auto"
  }
}

Video

{
  "content": {
    "videoLink": "https://youtube.com/watch?v=...",
    "autoplay": false,
    "muted": false,
    "loop": false,
    "controls": true
  }
}

Style Object

{
  "style": {
    "typography": {
      "fontFamily": "Inter",
      "fontSize": "16px",
      "fontWeight": "400",
      "lineHeight": "1.6",
      "letterSpacing": "0",
      "color": "#1e293b"
    },
    "spacing": {
      "margin": {
        "top": "0px",
        "right": "0px",
        "bottom": "16px",
        "left": "0px"
      },
      "padding": {
        "top": "0px",
        "right": "0px",
        "bottom": "0px",
        "left": "0px"
      }
    },
    "background": {
      "type": "solid",
      "color": "transparent"
    },
    "border": {
      "width": "0px",
      "style": "solid",
      "color": "#e2e8f0",
      "radius": {
        "topLeft": "0px",
        "topRight": "0px",
        "bottomRight": "0px",
        "bottomLeft": "0px"
      }
    }
  }
}

Advanced Object

{
  "advanced": {
    "htmlId": "my-element",
    "cssClasses": "custom-class another-class",
    "hideOnDesktop": false,
    "hideOnTablet": false,
    "hideOnMobile": false
  }
}

Children (Sections/Columns)

Sections contain columns, columns contain elements:

{
  "type": "section",
  "children": [
    {
      "type": "column",
      "content": {
        "columnWidth": "50%"
      },
      "children": [
        { "type": "heading", ... },
        { "type": "text", ... }
      ]
    },
    {
      "type": "column",
      "content": {
        "columnWidth": "50%"
      },
      "children": [
        { "type": "image", ... }
      ]
    }
  ]
}

Device-Specific Values

Many properties support device-specific values:

{
  "fontSize": {
    "desktop": "18px",
    "tablet": "16px",
    "mobile": "15px"
  }
}

Or as a simple value (applies to all devices):

{
  "fontSize": "16px"
}

Complete Example

{
  "id": "popup-123456789",
  "isOpen": true,
  "position": "center",
  "width": "500px",
  "backgroundType": "solid",
  "backgroundColor": "#ffffff",
  "borderRadius": "16px",
  "boxShadow": {
    "x": "0px",
    "y": "10px",
    "blur": "40px",
    "spread": "0px",
    "color": "rgba(0,0,0,0.2)"
  },
  "animation": "fadeIn",
  "trigger": "onload",
  "contentType": "elements",
  "elements": [
    {
      "id": "heading-1",
      "type": "heading",
      "order": 0,
      "content": {
        "text": "Welcome!",
        "level": "h2",
        "alignment": "center"
      },
      "style": {
        "typography": {
          "fontSize": "32px",
          "fontWeight": "700",
          "color": "#1e293b"
        }
      }
    },
    {
      "id": "button-1",
      "type": "button",
      "order": 1,
      "content": {
        "text": "Get Started",
        "link": "/signup",
        "target": "_self"
      },
      "style": {
        "background": {
          "type": "solid",
          "color": "#4F46E5"
        },
        "typography": {
          "color": "#ffffff"
        }
      }
    }
  ]
}

Validation

When importing JSON:

Required fields must be present
Types must match schema
IDs must be unique
Nested structures must be valid

Top-Level Structure​

Core Properties​

Identification​

Position​

Dimensions​

Background​

Gradient Object​

Border & Shadow​

Box Shadow Object​

Content​

Overlay​

Close Button​

Animation​

Trigger Properties​

Cookie Settings​

Element Schema​

Element Identification​

Element Types​

Content Object​

Text/Heading​

Button​

Image​

Video​

Style Object​

Advanced Object​

Children (Sections/Columns)​

Device-Specific Values​

Complete Example​

Validation​