Skip to content
Docs

Build a form that saves through the API

Any form that collects fields and submits them to the API uses the shared form scaffold: create and edit forms, renames, and confirm or delete dialogs that can fail with a server message. The scaffold provides validation, field errors, the form banner, and focus handling. Its exports and behavior are in Dashboard UI and forms.

Controls that only change local state, such as the scenario sliders of a document written in code, can use React state. Parameter writes follow Write parameter values from a dashboard.

Build the form

Section titled “Build the form”
  1. Create the form with useAppForm. Do not use bare useForm from @tanstack/react-form.
  2. Set real defaultValues. For a dialog, mount the form when the dialog opens and unmount it when the dialog closes, so it starts from the current values each time.
  3. Set validators: mutationFormValidators({ schema, submit }):
    • schema is the shared TypeBox form schema. Omit it only in a dialog that only confirms.
    • submit calls the mutation and returns null.
    • When the form field names differ from the API input, pass mapError: (error, value) => mapTrpcToFormErrors(error, value, { fieldMap }). Keep mapError pure, because it runs again whenever the message is read. Put side effects of a failure in onError.
  4. Set onSubmitInvalid: focusFirstInvalidField.
  5. Put success side effects, such as a success toast, navigation, or closing the dialog, in onSubmit only.
  6. Render form.AppForm, then form.FormRoot, then the fields and form.SubmitButton.
  7. When a submitted value must be converted to the API input, use the shared …FormToInput function and show its problem with formInputProblemErrors(result, message).

Confirm and delete dialogs use the same scaffold.

Show errors where operators look for them

Section titled “Show errors where operators look for them”
  1. Leave field errors to the scaffold: validation issues and API errors that name a field appear on that field, and other API failures appear in the form banner.
  2. Do not show a field-bearing submit’s error in a toast. Use error toasts only for actions without fields, such as an enable switch or a copy to the clipboard.
  3. Show API errors outside a form with apiErrorMessage, which reads the host catalog’s error_X message for code X. Translate the dashboard’s own error texts in its own message map.

Save the dashboard’s own configuration

Section titled “Save the dashboard’s own configuration”
  1. Use useDashboardConfigurationMutation with the dashboard’s TypeBox configuration schema and a transform of the stored configuration. It fails instead of overwriting a configuration that changed since it was read.
  2. For labels stored in the configuration, use DashboardConfigurationRenameDialog.
  3. For a parameter UUID field, use ParameterPickerField.

Check the form

Section titled “Check the form”
  • A field-level API error shows on the field, not only in a toast.
  • Other API failures show in the form banner (FormErrorBanner).
  • An invalid submit focuses the first invalid field.
  • A dialog form opens again with correct defaults.
  • API errors show translated text, never the English message.
Section titled “Related”