dolfindevelopers

Invoice form

ComponentReceivablesSDK + UI

A whole invoice: a server-searched customer picker (with an optional New Customer entry), currency, memo, CC for new invoices and payment terms with the due date if sent today, then the lines, discounts and live totals, and Create or Save. The same editor in both modes. By id it owns the draft: it loads the invoice (or starts a new one) and saves; onSubmit, submitting and submitDisabledReason replace the SDK's, and New Customer and New Product open the SDK's create dialogs (onCreateCustomer / onCreateProduct replace them, hideCreateCustomer / hideCreateProduct leave them out). Given values (the whole draft) it is controlled and saves nothing (values, onChange, errors, dirtyFields, onSubmit, submitting, submitDisabledReason). In both modes an option list you pass (customers, currencies, products, taxRates) is never fetched, and one you leave out is searched only once its picker opens. Also exports InvoiceDraftHeader, the header fields as a controlled editor part.

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

Choose your integration

Ready to connect to Dolfin. Loads data through SDK hooks, with appearance and behaviour you can customise. Requires DolfinProvider.

Loading preview…

Installation

Needs the Dolfin registry token. The CLI copies the source into your app.

Terminal
bunx --bun shadcn@4.23.0 add @dolfin/ar-invoice-form

Also installs: button, card, field, input, select, textarea, base-theme, base-info-hint, base-states, ar-invoice-lines-editor, ar-invoice-discount, ar-create-customer-dialog, ar-create-product-dialog, ui-ar-invoice-form.

Usage

screen.tsx
import { InvoiceDraftForm } from "@/components/dolfin/ar/invoice-draft-form";

// Place it anywhere inside your <DolfinProvider>.
<InvoiceDraftForm />

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

PropTypeDescription
invoiceIdstringBy id: edit this draft invoice; omit it (and `values`) to create one. The form loads it, edits it and saves.
initial{ customerId?: string; customerName?: string; currency?: string; }By id: starting values for a new invoice (for example, invoicing from a customer's page).
onSaved(invoice: Invoice) => voidBy id: called with the saved invoice.
valuesInvoiceDraftControlled: the whole draft (`useInvoiceDraft().draft`, or your own). The form draws the same editor as by id (fields, lines, discounts and totals), calls `onChange` with the next draft on every edit and saves nothing: Create or Save calls `onSubmit`. `values` wins over `invoiceId` when both are passed.
onChange(values: InvoiceDraft) => void
errorsReadonly<Partial<Record<string, string>>>A message per draft path (`customerId`, `lines`, `lines.0.quantity`, ...). By id, the API's.
dirtyFieldsreadonly string[]Paths changed since the invoice was saved (`useInvoiceDraft().dirtyFields`), ringed in edit mode.
formErrorstringControlled: a message for the whole form (`useInvoiceDraft().formError`).
mode"edit" | "create"Controlled: `create` (default) shows CC and says Create; `edit` says Save.
onSubmit() => voidCreate (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.
submittingbooleanThe save is running. By id, `undefined` means the SDK's own progress.
submitDisabledReasonstringA non-empty reason disables Create (or Save) and says why beside it; `""` keeps it enabled.
customersreadonly CustomerOption[]The customers to pick from. Given (`[]` included), the picker makes no request; left out, it searches them once it opens. The same for `currencies`, `products` and `taxRates`.
customersLoadingboolean
customersErrorError
onCustomersRetry() => void
customersCappedbooleanMore customers match than are listed: the picker asks for a narrower search.
onCustomerSearch(query: string) => voidWith `customers`: the customer search as typed, debounced 400ms.
currenciesreadonly { code: string; name: string; }[]The currencies the invoice may be raised in.
productsreadonly ProductOption[]The products a line can carry, in the invoice currency.
productsLoadingboolean
productsErrorError
onProductsRetry() => void
onProductSearch(query: string) => voidWith `products`: the product search as typed, debounced 400ms.
taxRatesreadonly TaxRateOption[]The tax rates a line can carry.
taxRatesLoadingboolean
taxRatesErrorError
onTaxRatesRetry() => void
onCreateCustomer() => voidOffers "New Customer" in the customer picker; open your create-customer dialog here. By id, yours replaces the SDK's create-customer dialog; controlled, the entry shows only with it.
onCreateProduct(lineKey: string) => voidOffers "New Product" in a line's product picker, with the line's key. By id it replaces the SDK's dialog.
hideCreateCustomerbooleanBy id: hides "New Customer" (the SDK's create-customer dialog).
hideCreateProductbooleanBy id: hides "New Product" (the SDK's create-product dialog).
customerPickerstring | number | bigint | boolean | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | React.Re…Replaces the customer picker (for example with your own customer search).
renderLineExtra(line: InvoiceDraftLine, index: number) => ReactNodeExtra fields under a line (for example an income account).
linesEmptyStatestring | number | bigint | boolean | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | React.Re…Replaces the note shown when there are no lines.
childrenstring | number | bigint | boolean | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | React.Re…Extra fields at the end of the header card.
classNamestring

Customisation

Without editing the source, you can change:

Class names
className
Messages
ar.invoiceDraftbase.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.

useCustomerOptionsuseDolfinLocaleuseInvoiceCurrenciesuseInvoiceDraftuseInvoiceDraftLookupsuseMessages

Files

Written to your app by the install command:

  • components/dolfin/ar/invoice-draft-form.tsx 371 lines
  • components/dolfin/ar/invoice-draft-header.tsx 134 lines
  • components/dolfin/ar/invoice-draft-form-fields.tsx 93 lines
  • components/dolfin/ar/invoice-draft-page-fields.tsx 75 lines
  • components/dolfin/ar/invoice-form-submit.tsx 39 lines
  • components/dolfin/ar/invoice-draft-create-dialogs.tsx 53 lines