Skip to main content

Widget props

Widget props provide the foundation for consistent behavior across all UI components in the Atlan Apps Framework. These shared properties handle common functionality like labeling, validation, layout positioning, and user guidance, allowing you to focus on widget-specific features while maintaining a unified user experience. Every widget inherits these base properties, creating predictable patterns for form construction and user interaction across all widget types.

Prop format​

Widget properties are defined in JSON. The structure below illustrates how properties control both behavior and presentation of a field in the Atlan Apps Framework.

{
  "field-name": {
    "type": "string",
    "ui": {
      "widget": "input",
      "label": "Field Label",
      "help": "Additional guidance text",
      "grid": 6,
      "start": 1,
      "rules": [
        {
          "required": true,
          "message": "This field is required"
        }
      ]
    }
  }
}

Each prop within the ui object controls a specific aspect of the widget's behavior and appearance:

  • type specifies the data type of the field (string).
  • ui.widget sets the UI element type (input).
  • ui.label provides a user-friendly label for display.
  • ui.help adds guidance text to assist users.
  • ui.grid and ui.start control layout positioning within a form grid.
  • ui.rules define validation logic, such as making the field required and showing an error message if the condition isn't met.

Props​

The following props are available for all widgets in the Atlan Apps Framework. Each prop controls specific aspects of widget behavior, appearance, and validation.

label​

Specifies the text displayed as the field label. The label appears next to the input field and helps users understand what information to enter. Use clear, familiar terms that match your audience's vocabulary.

Label examples
{
  "email": {
    "type": "string",
    "ui": {
      "widget": "input",
      "label": "Email Address"  // Clear and familiar
    }
  },
  "company": {
    "type": "string", 
    "ui": {
      "widget": "input",
      "label": "Company Name"  // Better than "Organization"
    }
  },
  "phone": {
    "type": "string",
    "ui": {
      "widget": "input", 
      "label": "Phone Number"  // More specific than just "Phone"
    }
  }
}

help​

Provides additional context displayed below the widget. Help text guides users by explaining data formats, providing examples, or clarifying the field's purpose. Keep help text concise and focused on what users need to successfully complete the field.

Help text examples
{
  "api-key": {
    "type": "string",
    "ui": {
      "widget": "credential",
      "label": "API Key",
      "help": "Found in your account settings under 'Developer Tools'"
    }
  },
  "start-date": {
    "type": "string",
    "ui": {
      "widget": "input",
      "label": "Start Date",
      "help": "Use YYYY-MM-DD format, for example 2024-03-15"
    }
  },
  "department": {
    "type": "string",
    "ui": {
      "widget": "input",
      "label": "Department",
      "help": "Optional - helps us route your request to the right team"
    }
  }
}

hidden​

Controls widget visibility in the UI. When set to true, the widget doesn't render but maintains its place in the form structure and validation rules. Useful for conditional logic, progressive disclosure, and storing values that don't need immediate user input.

Hidden field examples
{
  "user-type": {
    "type": "string",
    "ui": {
      "widget": "select",
      "label": "User Type",
      "options": ["basic", "advanced"]
    }
  },
  "advanced-endpoint": {
    "type": "string",
    "ui": {
      "widget": "input",
      "label": "Custom API Endpoint",
      "help": "Override the default endpoint URL",
      "hidden": true  // Show only when user-type is "advanced"
    }
  },
  "session-token": {
    "type": "string",
    "ui": {
      "widget": "input",
      "label": "Session Token",
      "hidden": true  // Always hidden, used for internal tracking
    }
  }
}

grid​

Grid column span for layout purposes. Defines how many columns the widget spans in the 12-column responsive grid system. Controls widget width using values 1-12, where grid: 6 takes half width and grid: 12 spans full width. The grid system automatically handles responsive behavior across different screen sizes.

Grid layout examples
{
  "title": {
    "type": "string",
    "ui": {
      "widget": "input",
      "label": "Title",
      "grid": 12  // Full width - good for longer text
    }
  },
  "first-name": {
    "type": "string", 
    "ui": {
      "widget": "input",
      "label": "First Name",
      "grid": 6  // Half width - sits next to last name
    }
  },
  "last-name": {
    "type": "string",
    "ui": {
      "widget": "input", 
      "label": "Last Name",
      "grid": 6  // Half width - completes the row
    }
  },
  "age": {
    "type": "string",
    "ui": {
      "widget": "input",
      "label": "Age", 
      "grid": 3  // Quarter width - good for short inputs
    }
  }
}

start and end​

Grid column positioning properties that work together with grid for precise layout control. The start property specifies which column the widget begins at (1-12), while end specifies where it concludes. These properties provide exact alignment and spacing control within the 12-column grid system when the basic grid property alone isn't sufficient for your layout needs.

Positioning examples
{
  "title": {
    "type": "string",
    "ui": {
      "widget": "input",
      "label": "Title",
      "grid": 12  // Full width using grid
    }
  },
  "first-name": {
    "type": "string",
    "ui": {
      "widget": "input",
      "label": "First Name",
      "start": 1,  // Starts at column 1
      "end": 6     // Ends at column 6 (spans 5 columns)
    }
  },
  "last-name": {
    "type": "string",
    "ui": {
      "widget": "input",
      "label": "Last Name", 
      "start": 7,  // Starts at column 7
      "end": 12    // Ends at column 12 (spans 5 columns)
    }
  },
  "priority-field": {
    "type": "string",
    "ui": {
      "widget": "input",
      "label": "Priority Level",
      "start": 4,  // Starts at column 4
      "end": 10    // Ends at column 10 (centered, 6 columns wide)
    }
  }
}

rules​

Validation rules for the input field. An array of rule objects where each rule can specify if the field is required and provide a custom error message. The structure is Array<{ required?: boolean; message?: string }>. Validation occurs in real-time as users interact with fields, providing immediate feedback for form completion.

Validation examples
{
  "api-key": {
    "type": "string",
    "ui": {
      "widget": "credential",
      "label": "API Key",
      "help": "Found in your account settings",
      "rules": [
        {
          "required": true,
          "message": "API key is required to connect"
        }
      ]
    }
  },
  "notes": {
    "type": "string",
    "ui": {
      "widget": "input",
      "label": "Additional Notes",
      "help": "Optional field for extra context"
      // No rules - field is optional
    }
  }
}

See also​