Validation Methods for Screen Components

Screen component validation uses these @api interface methods to communicate with Flow Builder. Understand implementation guidelines, best practices, and when the flow calls each method.

When a flow user navigates to another screen or finishes the flow, the validate() method provides the component’s internal validation status to the flow.

Use the validate() method to determine if the component has any internal errors, and return a { isValid: true/false, errorMessage: string } pair. Don't render internal errors inside the validate() method. Instead, use a set() method to validate properties and return internal error messages as needed.

Consider these best practices for implementing the method.

  • To prevent error messages from being shown on load, determine if a change has occurred within the component before showing any errors.
  • The set methods are called after the screen loads on the first visit or after a flow user moves to another screen or finishes the flow.
  • On the first visit to the screen, avoid showing users an error before they’ve interacted with the rendered components.
  • Show errors on screen load when the user is returned to the screen due to validate() returning an error. Following the best practices, @api reportValidity() causes the internal error to show.

If a component has an input validation error, the flow can send an external error message to the component by calling the setCustomValidity(externalErrorMessage) method only if one of these criteria is true:

  • The component is updated reactively.
  • A flow user moves to a new screen or finishes the flow.

The setCustomValidity(externalErrorMessage) method is not invoked with the result of the validate() method.

Implement this method to store externalErrorMessage in the local state. This is not a request from the flow to render error messages. The flow can call this method with an empty string to indicate that the external error has been resolved. In this situation, we recommend not showing the error. The component can render its internal and external errors at a later time in the reportValidity() method.

If externalErrorMessage is:

  • An empty string, then externalErrorMessage informs the component that an external error no longer exists.
  • Not an empty string, then externalErrorMessage contains the external error message corresponding to an input error that occurred from the flow at run time. The external error message is in rich text format.

To instruct the component to show internal and external errors, the flow calls the reportValidity() method if one of these occurs:

  • The flow moves to another screen or finishes and calls the validate() method that returns an error.
  • The component is updated reactively and has an input validation error.

Implement this method to render error messages in the component’s HTML. Determine how to display both internal and external errors. We recommend that you render all input validation and component validation errors in the reportValidity() method.

The flow calls the reportValidity() method along with the setCustomValidity(externalErrorMessage) method if one of these occurs:

  • An external error occurs such as an input validation error, for example:
    • setCustomValidity(externalErrorMessage) passes in the external error message.
    • reportValidity() requests that the component render the external error message.
  • The component has no external error but the component reports an error in the validate() method during a request to navigate away from the screen, for example:
    • setCustomValidity(externalErrorMessage) is called with an empty string because the flow had no external error to report.
    • reportValidity() requests that the component render the internal error message.

Understand when the flow calls the validation methods.

  • validate(): Called when the flow moves to the next screen or finishes.
  • setCustomValidity(externalErrorMessage): Called if an external error message exists or if the external error message is changed to an empty string.
  • reportValidity(): Based on these criteria, the flow calls the method.
    First Load of Flow Screen?Previously Has External Error?Has External Error?Has Internal Error?reportValidity() Called?Why?
    TrueNot applicableTrueTrueTrueMust render external error
    TrueNot applicableTrueFalseTrueMust render external error
    TrueNot applicableFalseTrueTrueMust render internal error that’s returned from the validate() method to show that the component failed due to moving to next screen or finishing the flow
    TrueNot applicableFalseFalseFalseNo errors to report
    FalseFalseTrueTrueTrueMust render external error
    FalseFalseTrueFalseTrueMust render external error
    FalseFalseFalseTrueFalseOptionally render internal error based on your implementation
    FalseFalseFalseFalseFalseOptionally render internal error based on your implementation
    FalseTrueFalseTrueTrueMust not render external error because it’s an empty string. Optionally render the internal error based on your implementation.
    FalseTrueFalseFalseTrueMust not render external error because it’s an empty string. Optionally render the internal error based on your implementation.

See Also