Record form

If your project doesn't have Wisty UI's theme yet, add it once with npx shadcn@latest add @wisty/cosmos. Until then, components keep shadcn's default look. Installation has the details.

fields describes every field the form can show, keyed by API name; each RecordFormField draws one by name. Saving is the app's: onSubmit gets the values, and the app passes pending and a failed save's errors back in. After Save & New, change the form's key to start again.

highlightChanges marks each field whose value differs from defaultValues, with an undo button that puts the default back, as Lightning's inline edit does. autoFocusField names the field whose control takes focus when the form mounts. onInvalidFields gets the fields the form's own checks stopped a save for, before focus moves, so a page can open the tab or section that hides one. It runs inside flushSync, so a plain setState there has shown the field when the form focuses it.

Values are keyed by API name: text, a number, a percent as a fraction (0.6 for 60%), true or false, a date as "YYYY-MM-DD", a datetime as an ISO 8601 instant ("2026-06-18T14:00:00.000Z"), a time as Salesforce's "HH:mm:ss.SSSZ" ("09:30:00.000Z"), a lookup's record id, an address's or a name's parts, or null for an empty field. A lookup's default value is its record ({ id, name }), so the field can show the name. In an edit, send changed, the second argument's values that differ from defaultValues, to updateRecord. A number is compared as the field shows it, rounded to its scale, so a default of 75000.005 at scale 2 is 75000.01 and isn't changed until someone edits it.

A datetime field is a date and a time on the clock of timeZone, an IANA zone that defaults to "UTC". Pass the user's Salesforce time zone (TimeZoneSidKey), so an event at "2026-06-18T14:00:00.000Z" reads 9:00 AM in "America/Chicago", and what they type saves as the instant it names there. A time field is a time of day with no zone, so timeZone never moves it. Both edit hours and minutes.

An address or a name is one field whose value is its parts: { street, city, state, postalCode, country } or { salutation, firstName, middleName, lastName, suffix }. Gather MailingStreet, MailingCity and the rest into it for defaultValues, and spread the submitted object back out to save, since Salesforce saves the parts, not the compound field. labels names each part, like "Mailing City":

A field whose control the form doesn't draw takes a custom control as RecordFormField's child. The field keeps its label, help, error and undo, and the control calls useRecordFormControl for the rest: value, as the form submits it, onValueChange, and controlProps to spread on the element people type in or pick from, so the label names it and a failed save focuses it. Describe the field in fields by the value it holds: text for a multi-select picklist's "English;Spanish", so the form's required check and changed apply. When the control holds an entry it can't read, pass onValueChange(null, { error }); the save stops there with that message. The Custom control example draws this picklist with Combobox:

To lay out a page layout you load at runtime, flatten each section's rows to field names and map them to parts:

• RecordFormSection is a static slds-section__title bar in slds-theme_shade, its title the size of Expandable section's, over an slds-form of slds-form__row rows and slds-form__item items, as a fieldset with the title as its legend.
• RecordFormField is a stacked form element (slds-form-element_stacked) with the control for its type: Input for text, email, phone and url, Textarea, Input group with the currency symbol or % for numbers, Date picker, Time picker, Select for a picklist, Lookup, and Checkbox under its label.
• A datetime is Datetime picker's compound form element: a FieldSet whose FieldLegend is the field's label, over the date picker and the timepicker (slds-timepicker) side by side, each with its own label.
• An address or a name is a compound form element (slds-form-element_compound, with slds-form-element_address for an address): a FieldSet whose FieldLegend is slds-form-element__legend, over slds-form-element__row rows of labelled parts. An address's street is a Textarea across, then City beside State/Province and Zip/Postal Code beside Country, four sixths and two. A name's salutation is a Select beside First Name, then Middle Name, then Last Name beside Suffix.
• A required field's label starts with slds-required, and RecordFormRequiredLegend is SLDS's legend for it. Help text is slds-form-element__icon's utility:info button with a tooltip, as lightning-helptext draws it.
• RecordFormMessages is an error Alert (slds-theme_error). Each field's error is its Field's error.
• With highlightChanges, a changed field is slds-is-edited, with slds-form-element__undo's utility:undo button at the end of its label's line.
• RecordFormSubmit is a brand button for Save and a neutral one for Save & New, with Spinner inside while the save runs.

Known gaps:

• No multi-select picklist, rich text or geolocation fields. Draw a scalar one with useRecordFormControl; an address, a name or a datetime takes no custom control.
• A datetime or a time edits hours and minutes. An untouched datetime submits its stored instant as it was. A time's stored seconds are dropped from what the form submits, though an untouched field isn't in changed.
• An address's parts and order are Salesforce's default (en-US) for every country, with free-text state and country; Lightning's country formats and state and country picklists aren't drawn. A name always shows all five parts, where an org without middle names and suffixes shows three.
• Sections don't collapse.
• No read-only fields in edit mode: leave out what people can't edit. Record inline edit draws them beside the form's fields.
• No error popover in the footer ("We hit a snag." next to the buttons). The record's errors show above the sections, as lightning-messages does.
• A number shows as typed, with the symbol beside it, where Lightning formats it when the field loses focus.

• Every control is named by its label, and each section is a group named by its title.
• An address or a name is a group named by its legend, so a part reads as "Mailing Address, Mailing City". A failed save focuses the first empty required part.
• A datetime is a group named by its label, and its halves are named after it, "Start Date" and "Start Time". A failed save focuses the half that's empty or can't be read, or the date when both are empty.
• A required field's control is required (a picklist's is aria-required). The asterisk is part of its label.
• An invalid field's control is aria-invalid and described by its error.
• A save that fails moves focus to the first field with an error, or to the record's errors when none belongs to a field on the page. Errors the form opens with don't take focus.
• A custom control is named by its field's label, required and invalid through controlProps, as long as the control spreads them on the element people focus.
• A field's help text is its help button's accessible description, so it's announced without opening the tooltip.
• An undo button is named "Undo" and the field's label, like "Undo Amount". It goes away once pressed, so focus moves to the field's control.
• While pending, the form is aria-busy, and the button that started the save holds a spinner named "Loading".

• A two-column section drops to one column when each would be narrower than 280px, by the section's own width, so it fits a narrow panel or modal.
• Labels follow Salesforce's display density: above the controls, and beside them from a 48rem screen when the page is compact (data-density="compact" on <html>). A field's layout ("stacked" or "horizontal") fixes it for that field.

• Put in fields only the fields the form shows. An error for a field the page doesn't draw is listed with the record's errors, under its label, or under its API name when it isn't in fields.
• Pass errors from state, a new object for each failed save. An edited field hides its error until the next save.
• Leave out a field people can't edit; never pass it to show it disabled.
• Pass null for an empty value, never "" or 0. A percent is a fraction: 0.6 for 60%. Divide a Salesforce percent field's 60 by 100.
• A required address needs every part, and a required name its last name. The asterisk is on the legend, and on Last Name for a name. Each empty part gets its own "Complete this field."; an error from the app for the field shows under the whole group.
• An address or a name submits every part, null for an empty one, and counts as changed when any part changed.
• A form never edits a relative time ("3 hours ago"); that's a read-only view of an instant.
• Pass a datetime as an instant, never as a local date and time, and set timeZone to the user's time zone. Pass a time as Salesforce returns it; it's never moved by timeZone.
• A custom control goes inside RecordFormField, which draws its label, error and undo. Spread controlProps on the element people focus, and never draw a label of its own.
• Pass a custom control's entry that isn't a value as onValueChange(null, { error }), never as a guessed value, so the save stops on it.
• Keep the footer inside RecordForm: Save is a submit button, and Save & New submits the form it's in.
• Never pass asChild or render.