Custom Entities

Custom Entities let you go beyond Wizflow’s 35+ built-in entities. They’re perfect when your workflow needs something specific — a custom input, a specialised integration, or a unique user interface.

Powered by Web Standards
Custom entities are built with JavaScript Web Components, supported by all modern browsers. Since version 3.9.0 the default way to write one is a React component, which Wizflow compiles into a web component for you. Plain web components still work.

Why use Custom Entities?

Industry-specific

Build entities tailored to your sector (finance, healthcare, legal, etc.)

Integration-focused

Connect directly to internal systems or third-party APIs

Advanced UI

Create rich interactive widgets that go beyond form fields

Reusable

Develop once and use across multiple flows or teams

Common use cases

Financial Services

Risk assessment calculators, compliance checklists, mortgage or pension widgets

Healthcare & Insurance

Adaptive medical forms, symptom checkers, coverage visualisers

Technical Tools

QR code scanners, digital signature pads, custom charts or dashboards

How it works

Plan – Define what data to collect and what experience to deliver
Generate – Describe the entity to the assistant, optionally with a reference image, and it writes a working React component
Refine – Keep talking to the assistant, or edit the code yourself in the editor
Configure – Decide what settings flow builders can customise (labels, ranges, formats)
Test & Publish – Preview the entity and make it available across flows

Start simple: even a small custom checkbox or lookup widget can add big value.

React components and the assistant

Version 3.9.0 changed how custom entities are written and how the assistant helps you write them.

Writing an entity in React

A custom entity is now a React component by default. You export one component as the default export; it receives two props:

attrs holds every configured attribute as a string, keyed by its kebab-case name. The entity’s own response arrives as attrs['response'].
dispatch sends events back to the chat, for example dispatch('submission', { value, args }) when the user answers.

Wizflow compiles the JSX and wraps the component in a web component, so the result runs in the chat like any built-in entity. React itself is shared with the chat page rather than bundled into each entity, which keeps entities small. Imports are limited to an allowlist:

Package	Use it for
`react`, `react-dom`	Components, hooks, portals
`nanoid`	Unique ids
`chart.js`	Charts. Import only the parts the chart needs, not `chart.js/auto`

Anything outside the list fails to compile with a message that names the package.

A better assistant

The assistant in the custom entity editor now works the way the live page assistant does. It writes and edits the code in the editor as you watch, compiles after every change and fixes its own errors, sets the entity’s name, description, input fields and response fields, seeds the preview with sample values, and takes a screenshot of the result to check its own work. When it needs a decision from you it asks a question and waits. You can paste a reference image with your prompt and ask the assistant to match it.

Be specific about data. Say what the entity receives (“category names and amounts”), what it should send back (“the chosen option and guest count”), and how the answer should read in the chat (“Coming with 3 guests”).

Existing entities

Entities built before 3.9.0 keep working unchanged, and you can still upload them. The assistant only edits React entities, so it will offer to upgrade an older entity before making changes to it. Response fields are now defined with the same field editor used elsewhere in the flow builder; older definitions are read as they are.

Browsing your custom entities

As the library grows, scrolling the Add entity panel stops working. Click Browse all custom entities at the bottom of the panel to open the whole library as a gallery. Each card shows a thumbnail of the rendered entity. Wizflow generates it when you publish the entity, or the first time the card is shown without one.

Search matches the entity’s name and description, and starts from whatever you had typed in the panel
Filter by author, and by questions or messages
Sort A-Z, newest first or oldest first

The menu on each card lets you add the entity to the flow, edit it, download it or delete it. Deleting an entity keeps it working in the flows that already use it, but it can no longer be added to a new one. The Create new entity tile opens the assistant.

Best practices

Performance

Keep entities lightweight and mobile-friendly
Avoid unnecessary dependencies

User experience

Follow familiar patterns
Provide clear labels, help text, and error states

Security

Validate all inputs
Use HTTPS for external calls
Handle sensitive data responsibly

Maintenance

Document options and usage
Plan for updates and backwards compatibility

Getting started

To create a custom entity:

Open Flow Builder
Go to Entities → Custom Entities → Create New
Describe what you want to the assistant (e.g. “mortgage calculator with loan amount, rate, and duration”)
Preview, refine, and save

Your entity will now appear in the entity palette alongside Wizflow’s built-in components.

Example

Here is a simple confirmation widget as a React entity:

import { useState } from 'react';

export default function ConfirmationSteps({ attrs, dispatch }) {
  const [done, setDone] = useState([false, false]);
  const toggle = (i) => setDone((d) => d.map((v, j) => (j === i ? !v : v)));

  return (
    <div>
      <h3>{attrs['heading'] ?? 'Please confirm the steps:'}</h3>
      <ul>
        <li><label><input type="checkbox" checked={done[0]} onChange={() => toggle(0)} /> Step 1</label></li>
        <li><label><input type="checkbox" checked={done[1]} onChange={() => toggle(1)} /> Step 2</label></li>
      </ul>
      <button disabled={!done.every(Boolean)} onClick={() => dispatch('submission', { value: 'confirmed', args: {} })}>
        All steps confirmed
      </button>
    </div>
  );
}

The same widget as a plain web component, the format used before 3.9.0:

class ConfirmationSteps extends HTMLElement {
  connectedCallback() {
    this.innerHTML = `
      <div>
        <h3>Please confirm the steps:</h3>
        <ul>
          <li><input type="checkbox" /> Step 1</li>
          <li><input type="checkbox" /> Step 2</li>
        </ul>
        <button>All steps confirmed</button>
      </div>
    `;
  }
}

customElements.define('confirmation-steps', ConfirmationSteps);

Flow Builder

Entities & Data Collection

Logic & Automation

Sharing & Embedding

Testing Tools

Why use Custom Entities?

Industry-specific

Integration-focused

Advanced UI

Reusable

Common use cases

How it works

React components and the assistant

Writing an entity in React

A better assistant

Existing entities

Browsing your custom entities

Best practices

Performance

User experience

Security

Maintenance

Getting started

Example

​Why use Custom Entities?

Industry-specific

Integration-focused

Advanced UI

Reusable

​Common use cases

​How it works

​React components and the assistant

​Writing an entity in React

​A better assistant

​Existing entities

​Browsing your custom entities

​Best practices

Performance

User experience

Security

Maintenance

​Getting started

​Example

Why use Custom Entities?

Common use cases

How it works

React components and the assistant

Writing an entity in React

A better assistant

Existing entities

Browsing your custom entities

Best practices

Getting started

Example