@wix/form-elements

The Wix Forms rendering element for Builder apps. @wix/form-elements/Form renders a form schema with the same engine the Forms app uses, and resolves language, currency, member context and submission on its own from the site's services.

How it reaches your site

At runtime the Wix builder platform resolves @wix/form-elements/Form through an import map to the component the Forms app deploys. This package is what your project imports at development time: it carries the types, and a bundle that behaves like the deployed component in tests, Storybook and the builder sandbox.

Declare the module as a component dependency so your build leaves the import to the platform:

resources: {
  client: {
    componentUrl,
    dependencies: {
      componentDependencies: ['@wix/form-elements/Form'],
    },
  },
},

Install it as a dev dependency next to react, react-dom and @wix/services-manager-react, which the platform provides and this package expects from its host. Everything else the element needs from the public registry (the Wix SDK modules, react-aria, ajv and the like) is a regular dependency of this package; only Wix-internal packages are bundled.

Rendering a form

import Form, {
  type FormSchema,
  type FormValues,
  type ValidationError,
} from '@wix/form-elements/Form';

const Step = ({ form, compId }: { form: FormSchema; compId: string }) => {
  const [values, setValues] = useState<FormValues>({});
  const [errors, setErrors] = useState<ValidationError[]>([]);

  return (
    <Form
      className="my-form"
      form={form}
      compId={compId}
      values={values}
      onChange={setValues}
      errors={errors}
      onValidate={setErrors}
      onSubmitSuccess={(submission) => markComplete(submission)}
    />
  );
};

Fetch the schema with the @wix/forms SDK and rename its _id-style keys with renameKeysFromSDKRequestToRESTRequest from @wix/sdk-runtime/rename-all-nested-keys; the element normalizes the layout itself.

| Prop | Purpose | | ------------------------------------- | ------------------------------------------------------------------------ | | form | The schema to render. Without it the element shows a notice. | | values / onChange | Controlled field values, keyed by field target. | | errors / onValidate | Controlled validation state. | | stepId / onStepIdChange | Controlled multi-step navigation. | | onSubmit | Fires when submission starts. | | onSubmitSuccess / onSubmitFailure | The created submission, or the rejection. | | compId | Scopes field ids so two instances on a page do not collide. | | id / className | On the element's wrapper, for layout and the editor selector. | | ref | FormHandle: submit(), validate(), validateStep(), getValues(). |

The stylesheet is exported as @wix/form-elements/Form/css, following the @wix/editor-react-components/<Name>/css convention. It is for renders outside the Wix platform: Storybook, standalone pages and Site Export, which imports <package>/<cssFile.path> from a component's moduleConfiguration. The Form's manifest (src/extensions/form/form.extension.ts) declares that configuration: this package, the Form entry and Form/css, so Site Export installs the component from npm instead of embedding a pre-built copy of the statics bundle. The entries and package.json#exports must change together. Don't import the stylesheet from component code: on a Wix site the platform loads the element's stylesheet itself, and the Wix CLI build would bundle a second copy into your component's CSS, since it only leaves @wix/form-elements/Form itself external.

What the package contains

• dist/component/form.js and its lazy chunks: the pre-built element. Wix-internal packages are bundled; packages on the public registry are imported from dependencies; react, react-dom and @wix/services-manager-react come from the host. Stylesheets are always bundled, even when they come from an external package such as @wix/ricos, so the JavaScript never imports CSS.
• dist/form.d.ts: the public types, rolled into one file that imports only react.
• dist/component/form.css.

Developing

This package is a Wix CLI app. yarn build generates translation keys, typechecks, pre-builds the element into dist/component, builds the extension and rolls up the types. yarn dev serves the extension and rebuilds the pre-build on change.

yarn test runs two Vitest projects. unit covers the source. package checks the built package in dist/, so it needs a build first; CI runs test after the build. It verifies that:

• dependencies matches exactly what the bundle imports.
• the bundle imports only peers and declared dependencies, that Node can load each of them without a bundler, that none reaches a stylesheet through its own module graph, and that the types import only react.
• each chunk group stays within its gzipped limit in .size-limit.json, checked by size-limit.
• the packed tarball passes publint and arethetypeswrong.
• the tarball installs into a fresh Vitest project and renders, including a rich-text field that loads @wix/ricos from that project's node_modules. It installs from Artifactory's mirror of registry.npmjs.org, which serves only public packages, so it fails if anything internal is needed. It takes a couple of minutes; yarn test --project unit skips the package checks.

The dependency list is derived, not maintained by hand. The pre-build leaves every public package as a bare import, except the ones in scripts/bundled-packages.mts, which carry the reason they must stay inside the bundle. When form-fields or form-viewer start importing a new public package, the dependency test fails; run node scripts/sync-dependencies.mts && yarn install and commit the manifest change. If the new import cannot be loaded by Node (CSS, extension-less deep imports), the import test fails; add the package to bundled-packages.mts with its reason instead.

See src/form-fields/*/*.md for the build and test integration notes.