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? True Not applicable True True True Must render external error True Not applicable True False True Must render external error True Not applicable False True True Must 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 True Not applicable False False False No errors to report False False True True True Must render external error False False True False True Must render external error False False False True False Optionally render internal error based on your implementation False False False False False Optionally render internal error based on your implementation False True False True True Must not render external error because it’s an empty string. Optionally render the internal error based on your implementation. False True False False True Must not render external error because it’s an empty string. Optionally render the internal error based on your implementation.
See Also
- Example: Custom Validation for Components in Flows
- Customize Input Validation Errors for Screen Components