Documentation
← Back to Module Development

Widgets & Fields

A comprehensive guide to configuring form fields, layouts, and visual behaviors in your modules.

Common Field Properties

Every field in your properties object supports a set of core settings that control its label, default value, and help text.

title

string

The Label. This is the human-readable text shown above the input field.
Why it's there: Without a title, the system will auto-generate a label from the key name (e.g., "my_field" becomes "My Field"), which often looks messy. Always provide a clean, descriptive title.

json
"message": { 
  "type": "string", 
  "title": "Banner Message" // <-- Displayed Label
}

description

string

The Helper Text. Renders a small tooltip icon next to the field label.
Why it's there: Use this to explain complex settings or formatting requirements without cluttering the UI. Hovering over the icon reveals the text.

json
"pixel_id": { 
  "type": "string", 
  "title": "Pixel ID",
  "description": "Find this in your Events Manager settings."
}

default

any

The Initial Value. Pre-fills the input field when the user adds a new module.
Why it's there: massively improves the "First Run Experience". Instead of a blank form, give users a working "Hello World" configuration so they can save and see results immediately.

json
"enabled": { 
  "type": "boolean", 
  "title": "Enable Banner",
  "default": true // <-- Toggle starts ON
}

format

string

Data Validation & UI Hint. Tells the system that a string should be treated as a specific data type. This automatically chooses the best input widget and applies validation rules (e.g. ensuring a URL is valid).

Format ValueUI WidgetValidation
"color"Color Picker + Hex InputMust be a valid hex color code (e.g. #ffffff)
"uri"URL InputMust be a valid absolute URL (http/https)
"email"Email InputMust be a valid email address
"date-time"Date & Time PickerISO 8601 Date String
"date"Date PickerISO 8601 Date (YYYY-MM-DD)

enum

array

Dropdowns & Choice Lists. To create a dropdown menu, simply provide an enum array of allowed values. Optionally, use oneOf with const and title for more readable labels (Title/Value pairs).

json
"position": { 
  "type": "string", 
  "title": "Position",
  "oneOf": [
    { "const": "top", "title": "Top of page" },
    { "const": "bottom", "title": "Bottom of page" }
  ],
  "default": "top"
}

Layout & Sizing

By default, every field takes up the full width of the container. You can create multi-column layouts using the x-layout property.

"x-layout": "full"

The default. Forces the property to take 100% of the row.

full

"x-layout": "five-sixths"

Takes up ~83% of the width. Often used with 'eighth' or spacing.

five-sixths

"x-layout": "half"

Splits the row into two. Two consecutive 'half' properties will sit side-by-side.

half
half

"x-layout": "third"

Perfect for sets of small inputs (e.g. Day, Month, Year).

third
third
third

"x-layout": "quarter"

Four items per row.

1/4
1/4
1/4
1/4

"x-layout": "eighth"

Tiny inputs (12.5% width). Useful for compact data entry.

...
...
...

Inline Styling

Use the x-style property to inject raw CSS styles directly into the input container.

json
"height": { "x-style": { "backgroundColor": "#f8fafc" } }

Advanced Configuration

Dependencies (Conditional Logic)

LinkWrangler supports standard JSON Schema dependencies. You can make fields appear only when another field has a specific value.

json
"dependencies": {
  "enable_custom_color": {
    "oneOf": [
      {
        "properties": {
          "enable_custom_color": { "const": true },
          "custom_color": { "type": "string", "format": "color" }
        },
        "required": ["custom_color"]
      }
    ]
  }
}

Field Ordering (x-order)

By default, fields appear in the order defined in properties. You can override this using x-order.

json
"x-order": ["name", "email", "advanced_settings"]