Widgets

Widgets control how a field looks in the UI.

The schema controls the data. The widget controls the interaction.

Example:

{
  "title": "Smoker",
  "type": "boolean",
  "x-widget": "checkbox"
}

Letting Tiep choose

Most of the time, do not set x-widget. Tiep can choose a good widget from the schema.

Set x-widget only when you need a specific UI.

Common widgets

Widget	Use it for
section	Object sections.
textarea	String, number, and integer free-input answers.
checkbox	Boolean answers.
buttonGroup	Very short choices.
select	One choice from enum, inline oneOf, or a concept set.
multiselect	Multiple choices from items.enum, items.oneOf, or an item concept set.
stringList	Free-form repeated strings.
list	Arrays.

The widget describes the control the user interacts with. Validation still comes from the schema type and constraints. For example, textarea with "type": "integer" renders as a numeric input and still validates as an integer.

Choice presentation comes from the schema:

• enum / items.enum means plain choices.
• oneOf / items.oneOf means inline coded concepts.
• x-concept-set-id on a scalar field, or on items for arrays, means a reusable concept set.

A concept-backed select or multiselect renders inline or as a search box depending on x-concept-mode. There is no separate coded or searchable widget.

Example: button group

"priority": {
  "title": "Priority",
  "type": "string",
  "enum": ["Routine", "Urgent"],
  "x-widget": "buttonGroup"
}

Example: concept multiselect

"diagnoses": {
  "title": "Diagnoses",
  "type": "array",
  "description": "Select all diagnoses relevant to this visit",
  "items": {
    "type": "string",
    "x-concept-set-id": 12
  },
  "x-widget": "multiselect"
}

Tiep decides inline vs. search from the set size. To force it, set x-concept-mode to inline or search on the field (or on items for a multiselect). See Concept sets.

Important rule

The widget must match the field type.

Bad:

{
  "title": "Age",
  "type": "number",
  "x-widget": "checkbox"
}

That does not make sense. Age is a number, not a yes/no answer.