@fillout/react

Fillout React Embeds

Embed Fillout forms directly in your React project. TypeScript included, no dependencies :)

Hint: If you're looking to use the Fillout API in Node.js, try @fillout/api!

• Setup
• Embed components
  • Standard embed
  • FullScreen embed
  • Popup embed
  • Slider embed
  • Popup and Slider embed buttons
• Listening for form events
• Custom domains

Setup

Install with npm i @fillout/react, and load the stylesheet with import "@fillout/react/style.css"

Embed components

There is a component for each embed type. All of them require the filloutId prop, which is the id of your form. This code is easy to spot in the url of the editor or the live form, for example, forms.fillout.com/t/foAdHjd1Duus.

All embed components allow you to pass URL parameters using the optional parameters prop, and you can also use inheritParameters to make the form inherit the parameters from the host page's url.

Standard embed

This one is pretty simple.

import { FilloutStandardEmbed } from "@fillout/react";
import "@fillout/react/style.css";

function App() {
  return (
    <div
      style={{
        width: 400,
        height: 400,
      }}
    >
      <FilloutStandardEmbed filloutId="foAdHjd1Duus" />
    </div>
  );
}

export default App;

If you'd rather not set the embed height manually and instead have it expand to the form size, use the dynamicResize prop.

FullScreen embed

The FilloutFullScreenEmbed component fills the entire page, with position: fixed.

import { FilloutFullScreenEmbed } from "@fillout/react";
import "@fillout/react/style.css";

function App() {
  return <FilloutFullScreenEmbed filloutId="foAdHjd1Duus" inheritParameters />;
}

export default App;

Popup embed

This component creates a popup, with a dark background covering the page content behind. Unlike the FullScreen embed, it can be closed using the close button or by clicking outside of the popup.

You control it using your own state. The isOpen and onClose props are required.

import { useState } from "react";
import { FilloutPopupEmbed } from "@fillout/react";
import "@fillout/react/style.css";

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Schedule a call</button>

      <FilloutPopupEmbed
        filloutId="foAdHjd1Duus"
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
      />
    </>
  );
}

export default App;

Slider embed

Similar to the popup embed, this is intended to be used alongside your own button and state, so the component requires isOpen and onClose props. The form will slide out from the side of the screen. You can control which direction it comes from using sliderDirection, which can be left or right (default).

import { useState } from "react";
import { FilloutSliderEmbed } from "@fillout/react";
import "@fillout/react/style.css";

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Schedule a call</button>

      <FilloutSliderEmbed
        filloutId="foAdHjd1Duus"
        inheritParameters
        parameters={{
          example: "abc",
        }}
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        sliderDirection="left"
      />
    </>
  );
}

export default App;

Popup and Slider embed buttons

If you would prefer not to manage the open state of a popup or slider yourself, you can use FilloutPopupEmbedButton or FilloutSliderEmbedButton. This will render a button that opens the embed when clicked. These components take the same props as their standalone counterparts (except for isOpen and onClose), but have some extra optional props to customize the button.

• text - change the button text
• color - change the button background color. the text color will automatically contrast with this as long as you specify a hex code.
• size - small, medium or large
• float - make your button float on the screen. bottomLeft or bottomRight.

import { FilloutSliderEmbedButton } from "@fillout/react";
import "@fillout/react/style.css";

function App() {
  return (
    <FilloutSliderEmbedButton
      filloutId="foAdHjd1Duus"
      inheritParameters
      parameters={{
        example: "abc",
      }}
      sliderDirection="left"
      text="Schedule a call"
      color="#444444"
      size="small"
      float="bottomRight"
    />
  );
}

export default App;

If you need greater control over the button appearance, you can just make your own and use it in conjunction with the standalone embed components.

Listening for form events

You can listen for certain form events using the onInit, onPageChange and onSubmit props. Each of these give the submission UUID as the first parameter, and the onPageChange prop gives the page ID as the second parameter.

import { FilloutStandardEmbed } from "@fillout/react";
import "@fillout/react/style.css";

function App() {
  return (
    <FilloutStandardEmbed
      filloutId="4SVaJQNVdrus"
      dynamicResize
      onInit={(submissionUuid) => {
        console.log(
          `User started filling out the form (submission ID: ${submissionUuid})`
        );
      }}
      onPageChange={(submissionUuid, pageId) => {
        if (pageId === "qTcp") {
          console.log("User is on the review step");
        }
      }}
      onSubmit={async (submissionUuid) => {
        const email = await doSomethingOnYourServer(submissionUuid);
        console.log(`${email} finished filling out the form`);
      }}
    />
  );
}

export default App;

This can be used in conjunction with the @fillout/api package on your server to get information about the structure of your form and to fetch field values once you have the submission UUID.

⚠️ The onPageChange may be triggered for any page on your form, including the starting page when the embed first loads. You should always check the page ID instead of making assumptions about where the user is in the form just because the function was triggered.

Custom domains

If you want to take advantage of features that are only available with forms hosted on your own domain, such as custom JS, you can use the domain prop to change the embedded url.

import { FilloutFullScreenEmbed } from "@fillout/react";
import "@fillout/react/style.css";

function App() {
  return (
    <FilloutFullScreenEmbed filloutId="foAdHjd1Duus" domain="example.com" />
  );
}

export default App;