@wpeform/react
TypeScript icon, indicating that this package has built-in type declarations

1.6.0 • Public • Published

WPEForm React SDK for Headless Forms

WPEForm WordPress Form Builder

www.wpeform.io

Next generation Drag and Drop Live Form Builder with payments, cost estimation, landing page, quizzes, personality tests, surveys, data collection and user feedback of all kinds. Create smarter & faster forms right inside WordPress.

WPEForm is the first of its kind, a WordPress Form Builder with Headless mode. The Plugin was written with JAMStack in mind. The backend is powered by a GraphQL API and the form itself is a TypeScript/React application.

So it is totally possible to create your form in your WordPress website and render it in some other React application.

This SDK includes all the necessary libraries needed to render WPEForms. All important libraries are kept as peer dependencies so you can use the same ones alongside your app.

The library comes with full typescript typings. So you get first-class editor support.

Installation

First follow the guidelines here to make sure you have enabled Headless Mode in WPEForm.

Now install this along with it's peer dependencies.

npx install-peerdeps @wpeform/react

This will install @wpeform/react along with needed peer dependencies. If you want to manually install, then here's the command:

npm install @wpeform/react \
  react \
  react-dom \
  react-is \
  react-latex-next \
  styled-components \
  query-string \
  @fortawesome/fontawesome-svg-core \
  @fortawesome/free-brands-svg-icons \
  @fortawesome/free-regular-svg-icons \
  @fortawesome/free-solid-svg-icons \
  @fortawesome/react-fontawesome \
  @apollo/client \
  @react-spring/web \
  zustand \
  @use-gesture/react \
  react-intersection-observer

As you can see, react and react-dom are kept as peers along with important libraries which you are probably using yourself.

Usage

Please see our official documentation for updated instruction on usage.

TL;DR

1. Enable headless mode in WordPress Plugin

Edit wp-config.php and put the following line.

define( 'WPEFORM_APP_MODE', true );

2. Copy the setup script to your website head

From WordPress Admin > WPEForm > Settings > System copy the setup script and put in your website head. Like this:

<!DOCTYPE html>
<html lang="en">
	<head>
		<title>My Awesome React App</title>
		<script type="text/javascript">
			var WPEFormGraphQLApp = {
				userPortal: 'https://yoursite.com/wp-eform/system/submissions/',
				summaryPage:
					'https://yoursite.com/wp-eform/system/summary/?mode=preview',
				gqlUri: 'https://yoursite.com/wp-eform/graphql/',
				freemius: {
					isTrial: false,
					isPlanStarterOrHigher: true,
					isPlanStarterOnly: false,
					isPlanProfessionalOrHigher: true,
					isPlanProfessionalOnly: false,
					isPlanBusinessOrHigher: true,
					isPlanBusinessOnly: true,
					canUsePremiumCode: true,
				},
				appVersion: '1.3.0',
			};
		</script>
	</head>
</html>

3. Start using the SDK

import React from 'react';
import { WPEForm } from '@wpeform/react';

export default function App() {
	return (
		<div>
			<h2>Behold my headless form</h2>
			<WPEForm formId="24" />
		</div>
	);
}

The export of @wpeform/react is lazy and accounts for SSR. If you want to import directly, do this

import { WPEForm } from '@wpeform/react/noLazy';

NOTICE: Do this only when your react application is client side only. Right now forms do not render server side. We will soon work on this though.

The WPEForm component accepts the following props:

type ThemeStyle = {
	scheme?: string;
	baseFont?: number;
	boldHeading?: boolean;
	italicHeading?: boolean;
	headFamily?: string;
	headFamilyCustom?: string;
	bodyFamily?: string;
	bodyFamilyCustom?: string;
	customPrimaryColor?: string | null;
	customSecondaryColor?: string | null;
	customBackgroundColor?: string | null;
	customTextColor?: string | null;
	css?: string | null;
	maxWidth?: string;
	containerLayout?: SettingsAppearanceContainerLayoutEnum;
	darkMode?: DarkThemeModeEnum;
};

type WPEFormProps = {
	/**
	 * The form Id to render.
	 */
	formId: string | number;
	/**
	 * Styles as received from server side render.
	 */
	themeStyle?: ThemeStyle | null;
	/**
	 * Number of panels for skeleton.
	 *
	 * @default 2
	 */
	panels?: number;
	/**
	 * Number of controls for skeleton.
	 *
	 * @default 3
	 */
	controls?: number;
	/**
	 * Whether or not to render the form in shadow dom, preventing conflict
	 * with your application.
	 *
	 * @default false
	 */
	inShadow?: boolean;
	/**
	 * Whether or not to override darkMode in forms. Works only if the theme
	 * has support for dark mode.
	 *
	 * undefined - No changed behavior, follow from the form config.
	 * true - Render form in dark mode.
	 * false - Render form in light mode.
	 */
	overrideDarkMode?: boolean;
};

Do read the official documentation for more tips and updated guide.

License

All files included in this repository are licensed under GPL-3.0 license.

This cannot be changed because dependencies used by this repository are also GPL-2.0 or later, especially the packed @wordpress dependencies. I may in future release the components library with MIT, but for now, this is the only package with everything.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

Versioning

Make sure you use the same version of the SDK as that of the plugin. For example if the plugin version is 1.5.2, make sure to use 1.5.2 of @wpeform/react package.

Package Sidebar

Install

npm i @wpeform/react

Weekly Downloads

3

Version

1.6.0

License

GPL-3.0

Unpacked Size

2.3 MB

Total Files

594

Last publish

Collaborators

  • swashata