onSubmit()

Overview#

onSubmit is a <Feathery.Form> prop and callback function to access and modify form state during successful form step submission. It's called every time the user successfully submits a step of the form. This function can be asynchronous.

Usage#

You can use onSubmit to store the submitted user data, update your rendered components, set custom errors, and more.

import { init, Form } from 'feathery-react';
function App() {
// Initialize Feathery to Peter
init('adminAPIKey', 'peter@feathery.io');
// Show the `onboarding` Feathery form
return <Form
formKey='onboarding'
// Store form data in backend
onSubmit={(context) => {
writeToBackend(context.submitFields);
if (context.lastStep) console.log("User finished form!");
}}
/>
}

Context Properties#

KeyTypeDescription
submitFieldsfieldData objectThe data of fields that the user just submitted.
elementRepeatIndexintegerSpecifies which repetition triggered form submission if the trigger is a repeating element. This value is 0-indexed and equals 0 if trigger doesn't repeat.
fieldsfieldData objectThe data of all fields in the form.
stepNamestringThe unique ID of the step.
userIdstringThe unique ID of the current user.
firstStepSubmittedbooleanTrue when onSubmit is first called for a form.
lastStepbooleanTrue when the step being submitted is the last step the user needs to complete.
triggerTypestring enumThe type of the submission trigger. Can be button, text, or field.
triggerKeystringIf type is field, the ID of the field. If button, the text on the button. If text, the text itself.
triggerActionstring enumclick if trigger was clicked, change if trigger field value was changed.
integrationDataobjectThird-party metadata may be passed back through this property. The firebaseAuthId and firebaseAuthToken properties are present when a pin_input field used to verify a Firebase SMS code is submitted.
setProgressfunctionIf a progress bar exists on the step, its progress will be set to the value passed in (0 - 100). If null is passed, the progress bar will default to its original value.
setStepfunctionIf you want to reroute the user to a different step, pass setStep the ID of the new step to route to. For example, setStep('new-step')
setValuesfunctionPass in an object of the shape {<fieldKey>: <fieldValue>} to customize internal form state
setOptionsfunctionPass in an object of the shape {<fieldKey>: [<fieldOption>]} to override the options a user can select for specific fields.
setErrorsfunctionPass in an object of the shape {<fieldKey>: <fieldErrorString>} to set errors for specific fields. An entry with the shape {<fieldKey>: {message: <fieldErrorString>, index: <fieldIndex>}} will set an error for a specific repeatable field across its repetitions. Setting an error prevents the step from submitting.

fieldData Object#

The object keys are unique field ID strings, defined by users in the Feathery dashboard. They map to objects that store additional field-specific information, defined below.

KeyTypeDescription
displayTextoptional stringText to display to your user along with the field
typestring enumField type (e.g. textarea, checkbox, etc.)
valueoptional polymorphicUser-submitted value for this field. null if no submission, Promise<File> if file submission, array of values if repeated.

fieldData Example#

{
age: {
displayText: 'How old are you?',
type: 'integer_field',
value: 21
},
photo_id: {
displayText: 'Upload a photo of your ID',
type: 'rich_file_upload',
value: Promise<File>
}
}

Return Value#

A promise can be optionally returned from this function if it's asynchronous and you want execution to await.