UI Schema

UI Schema is the protocol NocoBase uses to describe frontend components, based on Formily Schema 2.0 in a JSON Schema-like style. In FlowEngine, the uiSchema field in registerFlow uses this syntax to define the UI for configuration panels.

interface ISchema {
  type: 'void' | 'string' | 'number' | 'object' | 'array';
  name?: string;
  title?: any;
  // Wrapper component
  ['x-decorator']?: string;
  // Wrapper component props
  ['x-decorator-props']?: any;
  // Component
  ['x-component']?: string;
  // Component props
  ['x-component-props']?: any;
  // Display state, defaults to 'visible'
  ['x-display']?: 'none' | 'hidden' | 'visible';
  // Component's child content
  ['x-content']?: any;
  // Children node schema
  properties?: Record<string, ISchema>;

  // The following are only used for field components

  // Field reactions
  ['x-reactions']?: SchemaReactions;
  // Field UI interaction mode, defaults to 'editable'
  ['x-pattern']?: 'editable' | 'disabled' | 'readPretty';
  // Field validation
  ['x-validator']?: Validator;
  // Default data
  default?: any;
}

Basic Usage

Simplest Component

All native HTML tags can be converted to schema notation:

{
  type: 'void',
  'x-component': 'h1',
  'x-content': 'Hello, world!',
}

Equivalent JSX:

<h1>Hello, world!</h1>

Child Components

Children components are written in properties:

{
  type: 'void',
  'x-component': 'div',
  'x-component-props': { className: 'form-item' },
  properties: {
    title: {
      type: 'string',
      'x-component': 'input',
    },
  },
}

Equivalent JSX:

<div className={'form-item'}>
  <input name={'title'} />
</div>

Property Reference

type

The type of the node:

type SchemaTypes = 'string' | 'object' | 'array' | 'number' | 'boolean' | 'void';

name

The schema name. The name of a child node is the key in properties:

{
  name: 'root',
  properties: {
    child1: {
      // No need to write name here
    },
  },
}

title

The node title, typically used as the label for form fields.

x-component

The component name. Can be a native HTML tag or a registered React component:

{
  type: 'void',
  'x-component': 'h1',
  'x-content': 'Hello, world!',
}

x-component-props

Component props:

{
  type: 'void',
  'x-component': 'Table',
  'x-component-props': {
    loading: true,
  },
}

x-decorator

Wrapper component. The x-decorator + x-component combination allows placing two components in a single schema node — reducing structural complexity and improving reusability.

For example, in form scenarios, FormItem serves as the decorator:

{
  type: 'void',
  'x-component': 'div',
  properties: {
    title: {
      type: 'string',
      'x-decorator': 'FormItem',
      'x-component': 'Input',
    },
    content: {
      type: 'string',
      'x-decorator': 'FormItem',
      'x-component': 'Input.TextArea',
    },
  },
}

Equivalent JSX:

<div>
  <FormItem>
    <Input name={'title'} />
  </FormItem>
  <FormItem>
    <Input.TextArea name={'content'} />
  </FormItem>
</div>

x-display

The display state of the component:

Value	Description
`'visible'`	Show the component (default)
`'hidden'`	Hide the component, but data remains visible
`'none'`	Hide both the component and its data

x-pattern

The interaction mode of field components:

Value	Description
`'editable'`	Editable (default)
`'disabled'`	Not editable
`'readPretty'`	Read-pretty mode — for example, a text input component renders as `<input />` in edit mode and `<div />` in read-pretty mode

Usage in registerFlow

In plugin development, uiSchema is primarily used in registerFlow configuration panels. Each field is typically wrapped with 'x-decorator': 'FormItem':

MyModel.registerFlow({
  key: 'flow1',
  on: 'beforeRender',
  steps: {
    editTitle: {
      title: 'Edit Title',
      uiSchema: {
        title: {
          type: 'string',
          title: 'Title',
          'x-decorator': 'FormItem',
          'x-component': 'Input',
        },
        showBorder: {
          type: 'boolean',
          title: 'Show Border',
          'x-decorator': 'FormItem',
          'x-component': 'Switch',
        },
        color: {
          type: 'string',
          title: 'Color',
          'x-decorator': 'FormItem',
          'x-component': 'Select',
          enum: [
            { label: 'Red', value: 'red' },
            { label: 'Blue', value: 'blue' },
            { label: 'Green', value: 'green' },
          ],
        },
      },
      handler(ctx, params) {
        ctx.model.props.title = params.title;
        ctx.model.props.showBorder = params.showBorder;
        ctx.model.props.color = params.color;
      },
    },
  },
});

Tip

v2 is compatible with the uiSchema syntax, but its use cases are limited — it is mainly used in Flow configuration panels to describe form UI. For most runtime component rendering, it is recommended to use Antd components directly.

Common Components Quick Reference

Component	x-component	type	Description
Single-line text	`Input`	`string`	Basic text input
Multi-line text	`Input.TextArea`	`string`	Multi-line text area
Number	`InputNumber`	`number`	Number input
Switch	`Switch`	`boolean`	Boolean toggle
Dropdown select	`Select`	`string`	Requires `enum` for options
Radio	`Radio.Group`	`string`	Requires `enum` for options
Checkbox	`Checkbox.Group`	`string`	Requires `enum` for options
Date	`DatePicker`	`string`	Date picker

FlowEngine Overview (Plugin Development) — Practical usage of uiSchema in registerFlow
FlowDefinition — Complete parameter reference for registerFlow
Formily Schema Documentation — The underlying Formily protocol that uiSchema is based on

#UI Schema

#Basic Usage

#Simplest Component

#Child Components

#Property Reference

#type

#name

#title

#x-component

#x-component-props

#x-decorator

#x-display

#x-pattern

#Usage in registerFlow

#Common Components Quick Reference

#Related Links

UI Schema

Basic Usage

Simplest Component

Child Components

Property Reference

type

name

title

x-component

x-component-props

x-decorator

x-display

x-pattern

Usage in registerFlow

Common Components Quick Reference

Related Links