Skip to main content
A widget property schema defines its builder editor. Put each prop’s author-facing description on the field that produces that prop.

​
Define useful fields

Each prop-producing field needs:
  • a stable key;
  • a clear label;
  • a precise description;
  • a valid default when the field supports one.
Section headers and separators organize the editor but do not produce props. Use WidgetSourcePropertyField and WidgetSourcePropertySchema for current field types and required members.

​
Keep defaults valid

The widget’s defaultProps and field defaults must satisfy the same property contract. New widget instances should render a useful state without manual setup. Components must also handle missing, empty, partial, or malformed JSON without crashing.

​
Use theme-aware visual fields

Use colorSelect when an author must choose a color. It stores a semantic theme token. Do not add new uses of the deprecated color field. Prefer the host theme for typography, spacing, radii, borders, shadows, focus, and charts. Add a widget-owned visual field only when the product requirement cannot use a semantic theme value. See Runtime, styling, and accessibility for the supported theme-variable families and a complete CSS example.

​
Describe data-source results

When a prop exists only as a data-source result, describe it on the canonical data-source field and keep its target-prop mapping synchronized. Prefer host data sources and props to direct network requests.

​
Validate the editor contract

Test a new widget instance, every field type, empty data, and invalid persisted values. Confirm that author labels and descriptions explain the outcome rather than the implementation.