Form

​

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

• Component
• Configuration and Code

​

Churn Survey

• Component
• Configuration and Code

​

Dynamic Fields

• Component
• Configuration and Code

​

Branching Forms

• Component
• Configuration and Code

​

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.

steps:
  - id: step-1
    title: This is page 1
    fields:
      - id: email
        type: text
        props:
          type: email
          className: "my-custom-class"
          data-attr: "my-custom-data-attr"
          style:
            color: "red"

​

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:

import { FormFieldProps } from "@frigade/react";
import * as Frigade from "@frigade/react";

function CalendarField({ field, submit }: FormFieldProps) {
  return (
    <div>
      <input type="date" onChange={field.onChange} value={field.value} />
    </div>
  );
}

// ...

<Frigade.Form flowId="my-flow-id" fieldTypes={{ calendar: CalendarField }} />;

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:

import { type FormFieldProps, SelectField } from "@frigade/react";
import * as Frigade from "@frigade/react";

<Frigade.Form
  flowId="myflowid"
  fieldTypes={{
    "company-size": (props: FormFieldProps) => {
      const customerTypeValue = props.formContext.watch("customer-type");

      if (customerTypeValue !== "company") {
        return null;
      }

      return <div>My custom conditional field</div>;
    },
  }}
/>;

​

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:

steps:
  - id: collect-intend
    fields:
      - id: email
        type: text
        required: true
        pattern:
          message: Please provide a valid email
          value: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$

​

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.

import { StepHandlerProp } from "@frigade/react";
import * as Frigade from "@frigade/react";

const App = () => {
  const handlePrimary: StepHandlerProp = async (step, event, properties) => {
    const response = await fetch("https://my-server.com/validate", {
      method: "POST",
      body: JSON.stringify(properties),
      headers: {
        "Content-Type": "application/json",
      },
    });

    if (response.ok) {
      return true;
    }

    // The current step in the form will be marked as completed
    return false;
  };

  return <Frigade.Form flowId="my-flow-id" onPrimary={handlePrimary} />;
};

​

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:

​

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:

<Frigade.Checklist css={{ backgroundColor: "pink", ".fr-button-primary": { backgroundColor: "fuchsia" } }} />

​

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:

import { Form, FormFieldProps } from '@frigade/react'

function CalendarField({ field, submit }: FormFieldProps) {
  return (
   <div>
     <input type="date" onChange={field.onChange} value={field.value} />
   </div>
  )
}

 // ...

 <Form flowId="my-flow-id" fieldTypes={{ calendar: CalendarField }} />

​

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.

View definition