Recurring invoice form
The create and edit form for a recurring invoice, by id (omit scheduleId to create; contractTerms prefill a new one). It owns the draft and saves: customer (searched as you type), currency and memo; first invoice, cadence, number of invoices, payment terms and automatic sending, with start date and cadence locked once an invoice was generated; the line template with product, tax rate, quantity, fixed or live price and line discounts; the invoice discount, per-invoice figures and a one-sentence summary of the run. Field errors in place, unsaved edits ringed, a conflict notice, the contract banner, New customer and New product (the SDK's dialogs by id, or your onCreateCustomer / onCreateProduct), then Cancel (with onCancel) and Create or Save. Controlled with values, it saves nothing and an option list you pass is never fetched; one you leave out is searched once its picker opens.
Component: A piece you place inside your own screens: a table, a form, a card or a dialog. You decide the layout around it. Pages vs components
Ready to connect to Dolfin. Loads data through SDK hooks, with appearance and behaviour you can customise. Requires DolfinProvider.
Installation
Needs the Dolfin registry token. The CLI copies the source into your app.
bunx --bun shadcn@4.23.0 add @dolfin/ar-schedule-formAlso installs: button, card, command, input, label, popover, select, switch, textarea, base-theme, base-info-hint, base-money, base-page, base-states, ar-product-form, ar-schedule-parts, ar-schedule-contract, ar-create-customer-dialog, ar-create-product-dialog, ui-ar-schedule-form.
Usage
import { ArScheduleForm } from "@/components/dolfin/ar/schedule-form";
// Place it anywhere inside your <DolfinProvider>.
<ArScheduleForm />Renders inside DolfinProvider (set it up once). By default it loads its own data through the SDK. Supplied-data examples show how to override that behavior.
API reference
| Prop | Type | Description |
|---|---|---|
scheduleId | string | By id: edit this recurring invoice; omit it (and `values`) to create one. The form loads it, edits it and saves only the changes. |
contractTerms | { customerName?: null | string; customerEmail?: null | string; currency?: null | string; memo?: null | string; startDate?: null | string; ca… | By id, create only: start from terms read off a contract (shown under the contract banner). |
initial | { customerId?: string; customerName?: string; currency?: string; } | By id, create only: starting values, e.g. `{ currency: "EUR" }` or the customer when creating from a customer's page. `currency` replaces the organisation's default; a contract's own customer and currency still win. |
onSaved | (schedule: Schedule) => void | By id: called with the saved schedule. |
values | ScheduleDraft | Controlled: the whole draft (`useScheduleDraft().draft`, or your own). The form then draws these values, calls `onChange` with the next draft on every edit, and saves nothing itself: Create or Save calls `onSubmit`. `values` wins over `scheduleId` when both are passed. |
onChange | (values: ScheduleDraft) => void | |
errors | Partial<Record<string, string>> | Controlled: a message per draft path (`customerId`, `lines`, `lines.0.quantity`, ...). |
dirtyFields | readonly string[] | Controlled: paths changed since the schedule was saved (`useScheduleDraft().dirtyFields`), ringed in edit mode. |
onSubmit | () => void | Create (or Save). Controlled, the button shows only with it. By id, yours replaces the SDK's save: the form saves nothing and calls this instead. |
submitting | boolean | The save is running. By id, `undefined` means the SDK's own progress. |
formError | string | Controlled: a message for the whole form (`useScheduleDraft().formError`). |
mode | "edit" | "create" | Controlled: `create` (default) or `edit`, which draws the edit layout and says Save. |
anchorLocked | boolean | Controlled, edit: an invoice was generated, so the start date and cadence are locked. |
generated | number | Controlled, edit: invoices already generated (the count cannot go below it). |
prices | Record<string, number> | Controlled: the unit price per product id for live-priced lines (`useScheduleDraft().prices`). |
onCancel | () => void | Shows Cancel beside the submit button. |
submitDisabledReason | string | A non-empty reason disables the submit button and says why beside it; `""` keeps it enabled. By id, when you pass nothing, the SDK's reason applies (a role that can't manage recurring invoices). |
customers | readonly CustomerOption[] | The customers to pick from. Given (`[]` included), the customer picker makes no request: it filters these by name, or reports the search to `onCustomerSearch` (debounced 400ms) for you to load the matches. A list you leave out is searched for you, only once its picker opens. The same for `products`, `taxRates` and `currencies`. |
onCustomerSearch | (query: string) => void | |
products | readonly ProductOption[] | The products to pick from (only those in the schedule's currency are offered). Given, nothing is fetched. |
onProductSearch | (query: string) => void | With `products`: the line search as typed, debounced 400ms. |
taxRates | readonly TaxRateOption[] | The tax rates to pick from. Given, nothing is fetched. |
currencies | readonly { id?: string; code: string; name: string; symbol: string; decimalPlaces?: number | string; }[] | The currencies to pick from. Given, nothing is fetched. |
onCreateCustomer | () => void | Shows "New customer" in the customer picker (create only); open your own dialog. By id, yours replaces the SDK's create-customer dialog; controlled, the entry shows only with it. |
onCreateProduct | (lineKey: string) => void | Shows "New product" in a line's product picker, with the line's key. By id it replaces the SDK's dialog. |
hideCreateCustomer | boolean | By id: hides "New customer" (the SDK's create-customer dialog). |
hideCreateProduct | boolean | By id: hides "New product" (the SDK's create-product dialog). |
fields | string | number | bigint | boolean | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | React.Re… | Extra cards after the line items (e.g. delivery or accounting settings). |
errorState | string | number | bigint | boolean | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | React.Re… | By id: replaces the not-found, load error and ended state. |
className | string |
Customisation
Without editing the source, you can change:
- Class names
className- Messages
ar.customers.newCustomerar.products.newProductar.schedulesbase.infoHint.moreAbout
Or edit the installed file directly: it is your code. See theming for colours and fonts.
Hooks
The SDK hooks this component uses. Use them directly from @dolfinai/react to build your own version.
useCanManageSchedulesuseCustomerOptionsuseDolfinLocaleuseMessagesuseProductOptionsuseScheduleDraftuseScheduleDraftEditoruseTaxRateOptionsFiles
Written to your app by the install command:
components/dolfin/ar/schedule-form.tsx335 linescomponents/dolfin/ar/schedule-form-fields.tsx144 linescomponents/dolfin/ar/schedule-lines-editor.tsx281 linescomponents/dolfin/ar/schedule-pickers.tsx313 linescomponents/dolfin/ar/schedule-plan-summary.tsx71 linescomponents/dolfin/ar/schedule-create-dialogs.tsx70 lines