Invoice form
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
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-invoice-formAlso 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
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
| Prop | Type | Description |
|---|---|---|
invoiceId | string | By 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) => void | By id: called with the saved invoice. |
values | InvoiceDraft | Controlled: 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 | |
errors | Readonly<Partial<Record<string, string>>> | A message per draft path (`customerId`, `lines`, `lines.0.quantity`, ...). By id, the API's. |
dirtyFields | readonly string[] | Paths changed since the invoice was saved (`useInvoiceDraft().dirtyFields`), ringed in edit mode. |
formError | string | Controlled: a message for the whole form (`useInvoiceDraft().formError`). |
mode | "edit" | "create" | Controlled: `create` (default) shows CC and says Create; `edit` says Save. |
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. |
submitDisabledReason | string | A non-empty reason disables Create (or Save) and says why beside it; `""` keeps it enabled. |
customers | readonly 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`. |
customersLoading | boolean | |
customersError | Error | |
onCustomersRetry | () => void | |
customersCapped | boolean | More customers match than are listed: the picker asks for a narrower search. |
onCustomerSearch | (query: string) => void | With `customers`: the customer search as typed, debounced 400ms. |
currencies | readonly { code: string; name: string; }[] | The currencies the invoice may be raised in. |
products | readonly ProductOption[] | The products a line can carry, in the invoice currency. |
productsLoading | boolean | |
productsError | Error | |
onProductsRetry | () => void | |
onProductSearch | (query: string) => void | With `products`: the product search as typed, debounced 400ms. |
taxRates | readonly TaxRateOption[] | The tax rates a line can carry. |
taxRatesLoading | boolean | |
taxRatesError | Error | |
onTaxRatesRetry | () => void | |
onCreateCustomer | () => void | Offers "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) => void | Offers "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). |
customerPicker | string | 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) => ReactNode | Extra fields under a line (for example an income account). |
linesEmptyState | string | number | bigint | boolean | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | React.Re… | Replaces the note shown when there are no lines. |
children | string | number | bigint | boolean | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | React.Re… | Extra fields at the end of the header card. |
className | string |
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.
useCustomerOptionsuseDolfinLocaleuseInvoiceCurrenciesuseInvoiceDraftuseInvoiceDraftLookupsuseMessagesFiles
Written to your app by the install command:
components/dolfin/ar/invoice-draft-form.tsx371 linescomponents/dolfin/ar/invoice-draft-header.tsx134 linescomponents/dolfin/ar/invoice-draft-form-fields.tsx93 linescomponents/dolfin/ar/invoice-draft-page-fields.tsx75 linescomponents/dolfin/ar/invoice-form-submit.tsx39 linescomponents/dolfin/ar/invoice-draft-create-dialogs.tsx53 lines