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 from an `enum`
`sfo-radio-group`	`<sfo-radio-group-input>`	Flat radio-style option picker
`sfo-date-input`	`<sfo-date-input>`	Date input using the Angular Material datepicker
`sfo-date-variable-input`	`<sfo-date-variable-input>`	CSL date-variable input as plain text; stores a single-item string array
`sfo-rich-text`	`<sfo-rich-text-input>`	WYSIWYG-style rich text field
`sfo-textarea`	`<sfo-textarea>`	Multi-line text box
`sfo-code-editor`	`<sfo-textarea>`	Multi-line code/markup entry (currently rendered as a textarea)
`sfo-creator-role-array`	`<sfo-name-input>`	Author/creator list editor with person and literal (organisation) modes
`sfo-font-size-css`	`<sfo-font-size-css-input>`	Font-size input — a numeric value plus a unit or keyword

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.