React

Thin wrapper, not the runtime

The UI renders in the browser via the EWF runtime loaded from the CDN. This package is a thin wrapper that mounts it and bridges its events. It does not bundle the runtime.

Source: github.com/embedworkflow/embed-workflow-ui/packages/react
npm: @embedworkflow/react

Install

1
npm i @embedworkflow/react

react >= 17 is a peer dependency.

Prerequisites

Before any component renders, the page needs the EWF loader script and one auth call. This is the same for every SDK, so see the Embedding overview for the loader snippet and how to sign the JWT (server-side) and call load().

Sign JWTs server-side

Sign the JWT server-side. Never ship your secret key to the browser.

Getting started

The smallest working embed is a single field:

1
2
3
4
5
6
7
import { EwfField } from "@embedworkflow/react";

<EwfField
  workflowId="wf_123"        // or workflowKey="onboarding"
  fieldId="slack"            // field name or id in the workflow's form
  onChange={(e) => console.log(e.value, e.option)}
/>;

onChange receives EwfChangeDetail: { fieldId, value, option? }.

Components

One component per embeddable renderer. All accept className and style.

Component	Renders	Key props
`EwfApp`	The full workflow builder / app	`basePath`
`EwfSettingsForm`	A workflow's client settings form	`workflowId` \| `workflowKey`
`EwfConnections`	The managed connections UI	(none)
`EwfField`	A single field from a workflow's form	`workflowId` \| `workflowKey`, `fieldId`, `defaultValue`; emits `onChange`

`EwfApp`

1
<EwfApp basePath="workflows" style={{ height: "calc(100vh - 60px)" }} />

EwfApp has a few renderer requirements (no leading slash on basePath, an explicit non-% height, and a catch-all route). See Embedding the full app in the overview. In React Router that catch-all is path="/workflows/*".

Advanced

`EwfEmbed`

Embed any renderer by name, including ones this package version has no typed component for yet. It works for whatever the loaded CDN runtime supports, so a renderer newly shipped in the SDK is usable without upgrading this package.

1
2
3
4
import { EwfEmbed } from "@embedworkflow/react";

<EwfEmbed name="reports" data={{ "base-path": "reports" }} onChange={...} />;
// → <div class="EWF__reports" data-base-path="reports">

name: renderer class suffix ("reports" maps to EWF__reports).
data: keys map to data-<key>.

Prefer the named components when they exist; reach for EwfEmbed for dynamic names or renderers the package predates.

Other exports

createEmbed: build your own typed component (the named components are built on it).
useEwfMount: the low-level hook the components are built on. It mounts the element from a ref once the runtime is ready, wires ewf:change to onChange, and tears it down on unmount. Reach for it only when hand-rolling a custom wrapper.
Also exported: load and the EwfChangeDetail type.