UI Schema Widgets

UI Schema Widgets are specialized keywords embedded in your JSON Schema definitions. They instruct the dynamic form renderer in ui-components to use custom Angular components instead of default HTML input elements.

This allows for rich, opinionated UI controls that go beyond standard form behavior, like sfo-enum-input, sfo-radio-group, sfo-date-input, and more.

How it Works

When the form builder encounters a schema node with a @_ui_widget (aliased in code as SchemaKeywords.UiWidget), it renders the corresponding Angular component. If no @_ui_widget is specified, it falls back to traditional input types based on type, format, or enum.

Simplified Logic (Template)

if (schema[SchemaKeywords.UiWidget]) {
  renderCustomComponent(schema[SchemaKeywords.UiWidget]);
} else {
  renderBasedOnType(schema.type);
}

This lets you override default rendering behavior per field.

Examples

Example 1: Enum Input with Custom Widget

/**
 * @title Page breaks
 * @description Define the page break options used in the document.
 * @_ui_widget sfo-enum-input
 * @_nullable true
 * @_multiple true
 */
pageBreak?: (PageBreakType | null)[];

This schema field will render using the <sfo-enum-input> component, which supports multi-select, nullability, and tagging-style UX.

Example 2: Radio Group Selection

"placement": {
  "title": "Placement",
  "description": "Select where this content belongs in the document.",
  "_ui_group": "Structure",
  "_ui_widget": "sfo-radio-group",
  "enum": ["back", "body", "cover", "front"],
  "type": "string",
  "examples": [
    { "label": "Cover", "value": "cover", "description": "The cover page, typically unnumbered." },
    { "label": "Front", "value": "front", "description": "Roman numerals, different styling." },
    ...
  ]
}

The field will be rendered using <sfo-radio-group-input>, which formats the options into a clean radio-style UI based on the enum.

Supported UI Widgets

Keyword	Component	Description
sfo-enum-input	<sfo-enum-input>	Dropdown or tag-style multi-select
sfo-radio-group	<sfo-radio-group-input>	Flat radio-style option picker
sfo-date-input	<sfo-date-input>	Date input using Angular Material datepicker
sfo-rich-text	<sfo-rich-text-input>	WYSIWYG-style rich text field
sfo-textarea	<sfo-textarea>	Multiline text box
sfo-code-editor	<sfo-code-editor>	Embedded code editor (e.g. Monaco)

You can register and extend this list via a custom widget registry.

Tips for Schema Authors

• Use @_ui_widget when you need richer interactions than default fields provide. • Combine with other UI hints like @_ui_group, @_ui_class, or @_nullable for layout and UX control. • Provide @examples to give dropdowns or autocompletes rich data.