@nikhilll/auto-form-react
v0.1.0
Published
Let visitors fill your React forms by chatting (or speaking) with an assistant.
Maintainers
Readme
@nikhilll/auto-form-react
Let visitors fill your existing React forms by chatting with an assistant. The assistant asks for the details in one or two questions at a time, fills your inputs in place (including React-controlled ones), and explains validation errors. Visitors still review and submit the form themselves.
Install
npm install @nikhilll/auto-form-reactReact 18.2+ is a peer dependency; @nikhilll/auto-form-core comes with it. Works in Next.js (the components are client components).
To try an unreleased build, run npm run pack:widget in the auto-form-web repo and install both files from packed/ instead.
Use
import { AutoForm, AutoFormProvider } from '@nikhilll/auto-form-react'
export function ContactPage() {
return (
<AutoFormProvider publishableKey="pk_live_…" apiUrl="https://api.your-company.com">
<AutoForm formId="…">
<form onSubmit={save}>{/* your existing inputs, unchanged */}</form>
</AutoForm>
</AutoFormProvider>
)
}The publishable key and form id are on the app's page in the Auto Form dashboard. Add your site to the app's Websites (or allow localhost while developing).
Props
<AutoFormProvider>
| Prop | |
| ---- | - |
| publishableKey | The app's pk_live_… key. Safe to ship in browser code. |
| apiUrl | The Auto Form API origin. |
| client | Advanced, instead of apiUrl: an AutoFormClient you configured (endpoint, headers), e.g. for a proxy in front of the API. |
<AutoForm>
| Prop | |
| ---- | - |
| formId | A form confirmed in the dashboard. Omit it to have the assistant read the fields from the page (the app must allow detected forms). |
| name | Name of a detected form (defaults to the page title). |
| sessionId, sessionToken | For apps that require signed sessions: what your server got from POST /api/v1/server/sessions. |
| defaultOpen | Open the chat on page load. |
| onFieldFilled(key, value) | Called for each value the assistant fills. |
| onComplete(values) | Called after the visitor submits the form. |
| onReady() | Called once the assistant is set up and its chat button is showing. |
| onUnavailable(reason) | Called with a plain-English reason when the assistant can't run on this page (unknown key, site not allowed, form not attached or confirmed, API unreachable). The widget stays hidden either way; use this to log it or show your own message. |
Matching inputs to fields
Each field's key is matched to an input by data-af-field, then name, then id, then a name or id that reads the same (fullName matches full_name), then the label text. Radios and checkboxes that share a name are one field.
Optional attributes improve detected forms:
| Attribute | |
| --------- | - |
| data-af-field="key" | Explicit key |
| data-af-label="…" | Label for the assistant |
| data-af-type="phone" | Type when the input type is generic |
| data-af-hint="10 digits" | Format or example |
| data-af-required | Treat as required |
| data-af-sensitive | Never ask for this in chat |
| data-af-ignore | Skip this input (or everything inside the element) |
Passwords and file inputs are never read or filled.
How it behaves
- Starts on demand: a conversation starts when the visitor opens the chat, and resumes after a reload in the same tab.
- Fills as it goes: each value is written with the input's native setter followed by
input,changeandfocusoutevents, so React state, form libraries and validation see it. - Reports page problems: browser validation messages and your own messages (
aria-invalidwitharia-describedbyoraria-errormessage) go back to the assistant, which explains them to the visitor. - Tracks submission: submitting the wrapped form tells Auto Form, which then sends your app's webhook.
- Stays isolated: the widget renders in a shadow root, so your CSS and the widget's can't affect each other. It is marked
'use client'and renders nothing during server rendering. - Voice answers: if the app has voice answers on, visitors can tap the microphone, speak, and check the transcribed text before sending. It needs HTTPS, or localhost while developing.
- Fails quietly: if the site isn't allowed, the form isn't attached, or the app is off, the widget stays hidden and logs the reason to the console.
