KaaIoT, MikroTik & Teltonika Webinar. Build and Upgrade Equipment with IoT for Remote Access & Control
REGISTER NOW
NEW
Docs Webinars Get Support
Kaa Documentation

UI Schema Guide

UI Schema Guide

This guide covers the UI Schema (uiSchema) object used alongside the JSON Schema to control the presentation and behavior of forms rendered by react-jsonschema-form v1.6, including our custom extensions.

While JSON Schema defines what data to collect, UI Schema defines how to collect it.

Basic Structure

The uiSchema is an object where keys correspond to the property names defined in the JSON Schema. Each key holds an object specifying UI directives.

{
  "fieldName": {
    "ui:widget": "CustomSelectWidget",
    "ui:options": {
      "someOption": true
    },
    "ui:field": "CustomFieldTemplate"
  },
  "anotherField": {
    "ui:placeholder": "Enter a number here"
  },
  "objectContainer": {
    "ui:order": ["fieldInsideObject", "anotherFieldInside"],
    "fieldInsideObject": {
      "ui:widget": "textarea"
    }
  }
}

Standard UI Schema Directives Used

We leverage several standard react-jsonschema-form directives:

  • ui:widget: Specifies which component to use for rendering the input part of a field. This can be a standard HTML input type (text, textarea, radio, checkboxes, select, password, updown, range, hidden) or one of our custom widgets (see below).
  • ui:field: Specifies a custom component to render the entire field, including its label, description, and widget. This allows for more complex layouts or behaviors than just replacing the input widget. See Custom ui:field Components below.
  • ui:options: An object containing configuration specific to the chosen widget or field (standard or custom).
  • ui:order: An array of strings specifying the order in which properties within an object should be rendered. Use "*" to include any properties not explicitly listed.
  • ui:placeholder: Placeholder text for input fields.
  • ui:label: Set to false to hide the field’s label.
  • ui:help: Additional help text displayed below the field.
  • ui:disabled: Disables the field.
  • ui:readonly: Makes the field read-only.
  • ui:collapsed: For objects/arrays, controls the initial collapsed state (useful for complex sections).

Custom ui:widget Components

Our platform defines several custom widgets to provide tailored user experiences, replacing the standard input element:

  • Overridden Standard Widgets:
    • InputField (Base for text inputs)
    • CheckboxWidget (Checkbox)
    • TextareaWidget (InputField with multiline)
    • SelectWidget (MultiSelectField, enhanced with transformation)
    • TextWidget (InputField, enhanced with transformation)
    • RadioWidget (RadioButton)
  • Custom Widgets:
    • multiselect (MultiSelectField configured for multi-select)
    • select (AutocompleteMultiField, with transformation)
    • autocompleteMulti (AutocompleteMultiField configured for multi-select, with transformation)
    • templating (AutocompleteMultiField configured for creatable, multi-select templating, with transformation)
    • editableSelect (AutocompleteMultiField configured for creatable, single-select templating, with transformation)
    • livecomplete (LiveComplete)
    • JsonEditor (JsonQueryEditor)
    • JSONSchema (JSONSchema widget for rendering sub-schemas)
    • ColorPicker (ColorPicker)
    • DateControl (DateTimeControl)
    • DateRangeControl (DateRangeControl)
    • DateRangePicker (DateRangePicker)
    • ColorSelect (ColorSelect)
    • ColorPickerInput (ColorManualSelect)
    • Duration (Duration, with transformation)
    • FileUpload (FileUpload)
    • AvatarUploadWidget (AvatarUpload, with transformation)
    • ColorPalette (ColorPalette)
    • CheckboxGroup (CheckboxGroup, with transformation)
    • CodeEditor (CodeEditor)
    • ToggleButtonGroup (ToggleButtonGroupWidget)
    • ColorWheelPicker (ColorWheelPicker)

Custom ui:field Components

Custom fields provide complete control over the rendering of a field, including its label, help text, and the widget itself. They are used for highly specialized UI structures.

Available custom fields:

  • ThresholdField
  • BasicFormGeneratorField
  • VariablesField
  • ColumnWidth
  • UserListField
  • GroupListField
  • PolicyStatementsEditorField
  • LocationPicker

Use ui:field when you need a layout or interaction model not achievable by simply swapping the ui:widget.

Common Custom ui:options

While options are widget-specific, some common patterns appear, especially for custom widgets:

  • transformation: The core of dynamic behavior. This object defines how a widget (typically select-like widgets or templating) fetches or computes its data/options based on other form values. See the Transformations Guide for a detailed explanation.
  • addLabel: Custom label for the “Add” button in array fields.
  • multi / isMulti: Configures select widgets for multiple selections.
  • creatable: (For select/autocomplete widgets) Allows users to enter values not present in the predefined options.
  • supportsVariable: If set to true, allows the input field to accept dashboard context variables using the ${variableName} syntax (e.g., ${dashboard.id}).
  • lazy: enables pagination of options especially designed for the endpoints dataset
  • collapsed: (Used within options for complex widgets like JsonEditor, CodeEditor) Controls initial state.
  • hintTitle: Provides a tooltip or hint specifically for the widget.
  • fieldStyles: Allows passing custom CSS styles to the widget container.
  • search: (For array fields) Enables searching within array items (enabled, searchBy, placeholder).
  • lang: (For CodeEditor) Sets the language mode.
  • upload: (For FileUpload) Enables direct upload behavior.
  • units, convertTo: (For Duration) Configures duration units.
  • displayMode: (For DateRangeControl) Configures date range picker display.

See the sections below for detailed options of specific complex widgets:

Example: UI Schema

{
  "ui:order": ["header", "serviceIntegration", /*...*/ "*"] // Top-level field order
  "serviceIntegration": {
    "ui:collapsed": false, // Ensure this section is initially expanded
    "service": {
      "ui:widget": "SelectWidget", // Use our custom select widget
      "ui:options": {
        // Dynamic options based on available EPR service instances
        "transformation": { /* ... transformation definition ... */ }
      }
    },
    "applicationName": {
      "ui:widget": "SelectWidget",
      "ui:options": {
        // Dynamic options based on selected service
        "transformation": { /* ... transformation definition ... */ }
      }
    },
    "applicationSelection": {
      "ui:widget": "RadioWidget" // Use custom radio buttons
    }
  },
  "columns": {
    "ui:options": {
      "addLabel": "Add column", // Customize array button label
      "search": { // Enable searching within columns
        "enabled": true,
        "searchBy": "display",
        "placeholder": "form.placeholders.searchByName"
      }
    },
    "items": { // UI Schema for individual items within the 'columns' array
      "text": {
        "ui:widget": "templating", // Use templating input
        "ui:options": {
          "creatable": true,
          // Dynamic suggestions based on metadata keys
          "transformation": { /* ... transformation definition ... */ }
        }
      },
      "path": {
        "ui:widget": "SelectWidget",
        "ui:options": {
          "creatable": true,
          // Dynamic options based on metadata keys
          "transformation": { /* ... transformation definition ... */ }
        }
      }
      // ... other column item UI settings
    }
  }
}

This example demonstrates:

  • Top-level field ordering with ui:order.
  • Using custom widgets (SelectWidget, RadioWidget, templating).
  • Applying widget-specific options (addLabel, search, creatable).
  • Extensive use of ui:options.transformation to populate dropdowns dynamically (details in the Transformations Guide).

Refer to the base library documentation for base UI Schema features and explore widget/field source code for specific custom options.

Detailed Widget Options

FileUpload Options

Widget: FileUpload

Configuration for the file upload component.

  • upload: (Boolean) If true, enables direct file upload to a configured storage backend via the wdClient. If false or omitted, the widget typically returns the file content or name directly.
  • folder: (String) Specifies the target folder/path in the storage backend where the file should be uploaded (used when upload: true).
  • isPublic: (Boolean) Determines if the uploaded file should be publicly accessible (used when upload: true). Defaults to false.
  • checksumAlgorithm: (String, e.g., 'sha256') If provided, the backend calculates the checksum of the uploaded file using this algorithm, and the result is included in the onChange value alongside the URL (e.g., { url: '...', checksum: '...', checksumAlgorithm: 'sha256' }).
  • accept: (String) Standard HTML accept attribute value to filter file types in the browser’s file picker (e.g., "image/*", ".csv").
  • maxSize: (Number) Maximum allowed file size in bytes.

CodeEditor Options

Widget: CodeEditor

Configuration for the code editor component.

  • lang: (String) Sets the language mode for syntax highlighting and editor features. Examples: 'json', 'html', 'javascript', 'css'.
  • collapsed: (Boolean) If true, the editor section is initially collapsed.
  • maxWidth: (Number String) Sets the maximum width of the editor container (e.g., 800, "800px").
  • height: (Number String) Sets a specific height for the editor (e.g., 300, "300px").
  • linenumbers: (Boolean) Whether to show line numbers. Defaults to true.
  • htmlPreview: (Object) Configures an HTML preview pane alongside the editor:
    • enabled: (Boolean) If true, shows the preview pane.
    • orientation: (String: 'horizontal' 'vertical') Layout direction for editor and preview. Defaults to 'vertical'.
  • autocompleteFunction: (String) The name of a function registered in formContext.autocompleteFunctions to provide custom autocompletion suggestions.
  • hoverTooltipFunction: (String) The name of a function registered in formContext.hoverTooltipFunctions to provide custom tooltips on hover.

ColorSelect Options

Widget: ColorSelect

Provides a dropdown with predefined, named colors.

  • hintTitle: (String) A translation key or text for a hint tooltip displayed alongside the label.

(Note: This widget currently uses a hardcoded list of colors and doesn’t have many external configuration options via ui:options beyond standard ones like hintTitle.)

Duration Options

Widget: Duration

Input field specifically designed for entering time durations.

  • units: (Array) An array of allowed time units. Example: `['s', 'm', 'h', 'd', 'w', 'M', 'y']` (seconds, minutes, hours, days, weeks, months, years).
  • convertTo: (String) The unit to which the entered duration should be converted internally before being passed to onChange. Example: If units allows 'm' and 'h', and convertTo is 's', entering "5m" would result in onChange(300).
  • label: (Boolean) Set to false to hide the field label (useful when integrating tightly with other fields).
  • fieldStyles: (Object) Allows passing custom CSS styles to the widget container.
  • placeholder: (String) Placeholder text for the input.

Date/Time Control Options

This section covers options for DateControl, DateRangeControl, and DateRangePicker.

  • supportsVariable: (Boolean) For DateRangeControl, allows using dashboard variables like ${now-1h} in the date range input.

DateControl (Widget: DateTimeControl)

Used for selecting a single date and time.

  • includeTime: (Boolean) If true, allows selection of both date and time. If false or omitted, only date selection is available. Defaults to false.
  • skipValidation: (Boolean) If true, potentially bypasses some date format validation on input change. Use with caution.
  • supportsVariable: (Boolean) If true, allows the input to accept dashboard context variables (e.g., ${now-1h}).

DateRangeControl (Widget: DateRangeControl)

Combines presets and a custom range picker for selecting a date/time range.

  • supportsVariable: (Boolean) Enables the use of dashboard time variables.
  • displayMode: (String: 'picker' 'control') Determines the visual style. 'picker' typically shows an input field that opens a calendar, while 'control' might show more integrated controls. Defaults likely vary.
  • label: (Boolean) Set to false to hide the field label.
  • fieldStyles: (Object) Allows passing custom CSS styles.

DateRangePicker (Widget: DateRangePicker)

A direct date range calendar picker.

  • (Likely relies on standard schema properties. Check component source for specific ui:options if needed.)