Element Types

This document provides technical reference for all XBuilder element types, their properties, and default values.

Element Structure

All elements share a common structure:

interface BaseElement {
  id: string;           // Unique identifier
  type: ElementType;    // Element type
  order: number;        // Display order
  content?: object;     // Content properties
  style?: object;       // Style properties
  advanced?: object;    // Advanced properties
  children?: Element[]; // Child elements (sections/columns only)
}

Content Elements

Text (text)

Displays paragraph text content.

interface TextElement {
  type: 'text';
  content: {
    text: string;
    alignment?: 'left' | 'center' | 'right' | 'justify';
  };
  style: {
    typography: TypographyStyle;
    spacing: SpacingStyle;
  };
}

Default Values:

{
  "content": {
    "text": "",
    "alignment": "left"
  },
  "style": {
    "typography": {
      "fontSize": "16px",
      "fontWeight": "400",
      "lineHeight": "1.6",
      "color": "#1e293b"
    }
  }
}

Heading (heading)

Displays heading text (H1-H6).

interface HeadingElement {
  type: 'heading';
  content: {
    text: string;
    level: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
    alignment?: 'left' | 'center' | 'right';
  };
  style: {
    typography: TypographyStyle;
    spacing: SpacingStyle;
  };
}

Default Values:

{
  "content": {
    "text": "Heading",
    "level": "h2",
    "alignment": "left"
  },
  "style": {
    "typography": {
      "fontSize": "28px",
      "fontWeight": "700",
      "lineHeight": "1.2"
    }
  }
}

Button (button)

Clickable button element.

interface ButtonElement {
  type: 'button';
  content: {
    text: string;
    link?: string;
    target?: '_self' | '_blank';
    action?: 'link' | 'close' | 'submit';
    icon?: string;
    iconPosition?: 'before' | 'after';
  };
  style: {
    background: BackgroundStyle;
    typography: TypographyStyle;
    border: BorderStyle;
    spacing: SpacingStyle;
    hover?: HoverStyle;
  };
}

Default Values:

{
  "content": {
    "text": "Click Me",
    "link": "",
    "target": "_self",
    "action": "link"
  },
  "style": {
    "background": {
      "type": "solid",
      "color": "#4F46E5"
    },
    "typography": {
      "fontSize": "16px",
      "fontWeight": "600",
      "color": "#ffffff"
    },
    "border": {
      "radius": "8px"
    },
    "spacing": {
      "padding": {
        "top": "12px",
        "right": "24px",
        "bottom": "12px",
        "left": "24px"
      }
    }
  }
}

Image (image)

Displays an image.

interface ImageElement {
  type: 'image';
  content: {
    src: string;
    alt?: string;
    link?: string;
    target?: '_self' | '_blank';
    width?: string;
    height?: string;
    objectFit?: 'cover' | 'contain' | 'fill' | 'none';
  };
  style: {
    border: BorderStyle;
    spacing: SpacingStyle;
    shadow?: ShadowStyle;
  };
}

Default Values:

{
  "content": {
    "src": "",
    "alt": "",
    "width": "100%",
    "height": "auto",
    "objectFit": "cover"
  },
  "style": {
    "border": {
      "radius": "0px"
    }
  }
}

Video (video)

Embeds YouTube or Vimeo video.

interface VideoElement {
  type: 'video';
  content: {
    videoLink: string;
    autoplay?: boolean;
    muted?: boolean;
    loop?: boolean;
    controls?: boolean;
    startTime?: number;
  };
  style: {
    border: BorderStyle;
    spacing: SpacingStyle;
  };
}

Default Values:

{
  "content": {
    "videoLink": "",
    "autoplay": false,
    "muted": false,
    "loop": false,
    "controls": true
  },
  "style": {
    "border": {
      "radius": "8px"
    }
  }
}

Icon (icon)

Displays a Font Awesome icon.

interface IconElement {
  type: 'icon';
  content: {
    icon: string;      // e.g., "fa-solid fa-star"
    link?: string;
    target?: '_self' | '_blank';
  };
  style: {
    size: string;
    color: string;
    background?: BackgroundStyle;
    border?: BorderStyle;
  };
}

Default Values:

{
  "content": {
    "icon": "fa-solid fa-star"
  },
  "style": {
    "size": "24px",
    "color": "#4F46E5"
  }
}

Layout Elements

Divider (divider)

Horizontal separator line.

interface DividerElement {
  type: 'divider';
  style: {
    width: string;
    thickness: string;
    color: string;
    style: 'solid' | 'dashed' | 'dotted';
    alignment?: 'left' | 'center' | 'right';
    spacing: SpacingStyle;
  };
}

Default Values:

{
  "style": {
    "width": "100%",
    "thickness": "1px",
    "color": "#e2e8f0",
    "style": "solid"
  }
}

Spacer (spacer)

Empty vertical space.

interface SpacerElement {
  type: 'spacer';
  style: {
    height: string | DeviceValues;
  };
}

Default Values:

{
  "style": {
    "height": "24px"
  }
}

Container Elements

Section (section)

Row container that holds columns.

interface SectionElement {
  type: 'section';
  content: {
    gap?: string;
    verticalAlign?: 'top' | 'center' | 'bottom' | 'stretch';
  };
  style: {
    background?: BackgroundStyle;
    spacing: SpacingStyle;
    border?: BorderStyle;
  };
  children: ColumnElement[];
}

Default Values:

{
  "content": {
    "gap": "24px",
    "verticalAlign": "top"
  },
  "children": []
}

Column (column)

Column container within a section.

interface ColumnElement {
  type: 'column';
  content: {
    columnWidth: string;  // e.g., "50%", "33.33%"
    horizontalAlign?: 'left' | 'center' | 'right';
    verticalAlign?: 'top' | 'center' | 'bottom';
  };
  style: {
    background?: BackgroundStyle;
    spacing: SpacingStyle;
    border?: BorderStyle;
  };
  children: Element[];
}

Default Values:

{
  "content": {
    "columnWidth": "100%",
    "horizontalAlign": "left",
    "verticalAlign": "top"
  },
  "children": []
}

Embed Elements

Maps (maps)

Google Maps embed.

interface MapsElement {
  type: 'maps';
  content: {
    address?: string;
    latitude?: number;
    longitude?: number;
    zoom?: number;
    mapType?: 'roadmap' | 'satellite' | 'hybrid' | 'terrain';
    showMarker?: boolean;
  };
  style: {
    width: string;
    height: string;
    border?: BorderStyle;
  };
}

Default Values:

{
  "content": {
    "address": "",
    "zoom": 14,
    "mapType": "roadmap",
    "showMarker": true
  },
  "style": {
    "width": "100%",
    "height": "300px"
  }
}

Iframe (iframe)

External content embed.

interface IframeElement {
  type: 'iframe';
  content: {
    src: string;
    title?: string;
    scrolling?: 'auto' | 'yes' | 'no';
    allowFullscreen?: boolean;
  };
  style: {
    width: string;
    height: string;
    border?: BorderStyle;
  };
}

Default Values:

{
  "content": {
    "src": "",
    "title": "",
    "scrolling": "auto",
    "allowFullscreen": false
  },
  "style": {
    "width": "100%",
    "height": "400px",
    "border": {
      "width": "0px"
    }
  }
}

Shared Types

Typography Style

interface TypographyStyle {
  fontFamily?: string;
  fontSize?: string | DeviceValues;
  fontWeight?: string;
  lineHeight?: string;
  letterSpacing?: string;
  color?: string;
  textAlign?: 'left' | 'center' | 'right' | 'justify';
  textTransform?: 'none' | 'uppercase' | 'lowercase' | 'capitalize';
  textDecoration?: 'none' | 'underline' | 'line-through';
}

Spacing Style

interface SpacingStyle {
  margin?: BoxSpacing;
  padding?: BoxSpacing;
}

interface BoxSpacing {
  top?: string;
  right?: string;
  bottom?: string;
  left?: string;
}

Border Style

interface BorderStyle {
  width?: string;
  style?: 'solid' | 'dashed' | 'dotted' | 'none';
  color?: string;
  radius?: string | {
    topLeft?: string;
    topRight?: string;
    bottomRight?: string;
    bottomLeft?: string;
  };
}

Background Style

interface BackgroundStyle {
  type: 'solid' | 'gradient' | 'image' | 'none';
  color?: string;
  gradient?: GradientStyle;
  image?: string;
}

Shadow Style

interface ShadowStyle {
  x: string;
  y: string;
  blur: string;
  spread: string;
  color: string;
}

Device Values

interface DeviceValues {
  desktop: string;
  tablet?: string;
  mobile?: string;
}

Element ID Format

XBuilder generates element IDs in this format:

{type}-{timestamp}{random}

Examples:

• heading-1704067200123
• button-1704067200456
• section-1704067200789