Form
Collect user information via inline or modal forms
About this component
The Frigade Form component is one of the most versatile and customizable components in the Frigade SDK. It can be used for wide range of use cases including registration flows, surveys, feedback forms, and more. The component supports form validation (client and server-side), conditional fields, branching logic, and multi-step flows out of the box.
Related resources
- Create a form and send events to Slack
- Launch pop-up forms and surveys with no-code using Collections
- Target your form to specific users with Targeting
- See the open source Frigade Demo Form example
Examples
The following section contains a series of ready-to-use examples that demonstrate how to use the Frigade Form component in different scenarios.
Simple Modal Form
Churn Survey
Dynamic Fields
Sometimes you may want to conditionally render a dynamic field based on the value of another field. The example above dynamically changes the second dropdown based on the value of the first dropdown.
Branching Forms
This example shows how to implement branching in a form based on the user’s choice in the first step.
Supported Field Types
The component supports the following builtin field types that correspond to their respective HTML input types:
select
radio
text
textarea
checkbox
Overriding Field Attributes
You can override or add any attribute for a field by using the props
property in the field configuration.
For instance, this is useful if you want to use the text
field type, but override the type
to email
or tel
. It can also be used to add any attribute such as a css class, data, or styling.
Custom Field Types
The Form SDK is built on top of react-hook-form, which means you can use the majority of its features in your forms. You can define your own custom field types using the fieldTypes
prop.
For instance, you can implement a simple calendar datepicker field type as such:
It is also possible to conditionally render a field based on the value of another field by using the formContext provided by react-hook-form.
For instance, if you want a custom field called company-size
to show up when a user selects company
in the customer-type
field:
Form Validation
The component supports client-side and server-side validation out of the box. You can define validation rules for each field in the form configuration using the pattern
property with a regular expression. The example below shows how to validate an email field:
Server-side Validation
You can perform server-side validation by returning a Promise from the onPrimary
event handler. If the promise resolves to false
, the current step in the form will not be marked as completed. The onPrimary
event handler also contains all form data collected in the session, which allows you to send the data to your server for validation or storage.
Prefilling a form
Forms can be prefilled by using Dynamic Variables by linking the value
of a field
to the variables
prop of the Form component. The example below shows how to prefill a form with the user’s name:
Flow Configuration
The following props are available in the YAML Config defined in the Frigade Dashboard:
The individual steps/pages of the form
Unique identifier for the step. Do not change this once the step has been created.
The title of the step
The description of the step
Url to an image to display in the step
Url to an icon to display in the step. This is only supported by the carousel checklist component.
Url to a video to display in the step such as YouTube, Vimeo, or a direct link to an mp4 file
Config for the primary button in this step.
Primary button action. (defaults to step.complete).
Possible values: false
, flow.back
, flow.complete
, flow.forward
,
flow.restart
, flow.skip
, flow.start
, step.complete
, step.skip
,
step.reset
, step.start
Primary button URI target (defaults to _self).
Primary button title. If omitted, the primary button will not be shown.
Primary button URI.
Deprecated: use primaryButton.title
instead. The title of the primary
button
Deprecated: use primaryButton.uri
instead. The url to open when the
primary button is clicked
Deprecated: use primaryButton.target
instead. The target of the primary
button url (default: _blank; use _self to open in the same window). Setting it
to # will open the existing page and dismiss any Frigade modals.
Config for the secondary button in this step.
Secondary button action. (defaults to step.complete).
Possible values: false
, flow.back
, flow.complete
, flow.forward
,
flow.restart
, flow.skip
, flow.start
, step.complete
, step.skip
,
step.reset
, step.start
Secondary button URI target (defaults to _self).
Secondary button title. If omitted, the secondary button will not be shown.
Secondary button URI.
Deprecated: use secondaryButton.title
instead. The title of the
secondary button
Deprecated: use secondaryButton.uri
instead. The url to open when the
secondary button is clicked
Deprecated: use secondaryButton.target
instead. The target of the
secondary button url (default: _blank; use _self to open in the same window).
Setting it to # will open the existing page and dismiss any Frigade modals.
Targeting that automatically completes the step. E.g.: user.property(‘connectedBank’) == true
Targeting that automatically blocks the step from starting until it becomes true. E.g.: user.property(‘connectedBank’) == true
Targeting that automatically shows the step when it becomes true. E.g.: user.property(‘connectedBank’) == true
Override the default UI props for the corresponding component
The data contained on the form step, typically text input boxes, multiple choice questions, etc.
Unique identifier for the step. Do not change this once the step has been created.
The label of the field
The default value of the field (used for prefilling). For checkboxes, use ‘true’ or ‘false’.
Whether the field can accept multiple values. Only used for the select
type
field.
The type of the field. The built-in supported types are: text
, textarea
,
select
, checkbox
, and radio
. If you are using custom form field types,
the name here should match it.
The placeholder of the field
The maximum length of the field
Whether the field is required or not. Use a string here to show a custom error message.
The options for the field. Only used for select fields.
The label of the option
The value of the option
The validation rules for the field. See documentation for more information.
Regex pattern to match the field against
The error message to display if the pattern does not match
Optional additional properties for the field. These will be passed to the frontend component as HTML attributes and merged with the default props for the given field type.
React Component Props
as
Optional
as: ElementType
<any
, keyof IntrinsicElements
>
Optional component to wrap the child components in, e.g. as={Dialog}
will render the Flow in a modal Dialog. Defaults to Box
.
css
Optional
css: Interpolation
<Theme
>
Emotion CSS prop to apply to the component. See Theming documentation for more information.
Example usage:
dismissible
Optional
dismissible: boolean
Whether the Flow is dismissible or not
fieldTypes
Optional
fieldTypes: FieldTypes
Custom field types to be used in the Form.
You can use this to build your own custom form fields in a Form
.
For example, if you want to use a custom field type called calendar
:
flowId
flowId: string
The Flow ID to render. You can find the Flow ID in the Frigade dashboard.
forceMount
Optional
forceMount: boolean
If true, the Flow will be mounted even if it has already been completed or dismissed. However, if the user does not match the Flow’s targeting, the Flow will not be mounted.
modal
Optional
modal: boolean
Register the Flow as a modal to prevent popup collisions (only one modal Flow will render at a time).
onComplete
Optional
onComplete: FlowHandlerProp
Handler for when the Flow is completed. This is event is fired immediately after the user completes the Flow.
onDismiss
Optional
onDismiss: FlowHandlerProp
Handler for when the Flow is dismissed (skipped). This is event is fired immediately after the user dismisses the Flow.
onPrimary
Optional
onPrimary: StepHandlerProp
Handler for when primary button is clicked.
If this function a promise that evaluates to false
, the step will not be automatically completed when clicked.
onSecondary
Optional
onSecondary: StepHandlerProp
Handler for when secondary button is clicked.
If this function a promise that evaluates to false
, the step will not be automatically completed when clicked.
variables
Optional
variables: Record
<string
, unknown
>
Variables to pass to the Flow. You can use variables in the Flow configuration to customize copy.
For instance, you can use title: Hello, ${name}!
in the Flow configuration and pass variables={{name: 'John'}}
to customize the copy.