Record Edit Form

Use the lightning-record-edit-form component to create a form that's used to add a Salesforce record or update fields in an existing record on an object. The component displays fields with their labels and the current values, and enables you to edit their values.

lightning-record-edit-form supports the following features.

• Editing a record's specified fields, given the record ID.
• Creating a record using specified fields.
• Customizing the form layout
• Custom rendering of record data

If you don't require customizations, use lightning-record-form instead.

To specify editable fields, use lightning-input-field components inside lightning-record-edit-form component. See the Editing a Record section.

To display record fields as read-only in lightning-record-edit-form, use lightning-output-field components to specify those fields. You can also use HTML and other display components such as lightning-formatted-name to display non-editable content.

To display all fields as read-only, use the lightning-record-form component with mode="readonly" or the lightning-record-view-form component instead of lightning-record-edit-form.

To understand the different use cases, see Work with Records Using Base Components.

lightning-record-edit-form implements Lightning Data Service and doesn't require additional Apex controllers to create or update record data. This component also takes care of field-level security and sharing for you, so users see only the data they have access to. For more information, see Lightning Data Service.

When possible, let lightning-record-edit-form load and manage the data for you as it implements Lightning Data Service. Using lightning-record-edit-form to create or update records with Apex controllers can lead to unexpected behaviors. Additionally, data provisioned by Apex is not managed and you must handle data refresh by invoking the Apex method again on your own.

To access raw record data or create a form that needs more customization than the lightning-record-*-form components allow, use Lightning Data Service wire adapters and functions, such as those from the lightning/ui*Api module.

You can use Apex if you are working with an object that's not supported by the User Interface API, or if you have to use a SOQL query to select certain records. See the Supported Objects section.

Each Salesforce record is associated with a Salesforce object. For example, a contact record is associated with the Contact object. Record IDs are created with prefixes that indicate the object. The lightning-record-edit-form component requires you to specify the object-api-name attribute to establish the relationship between a record and an object. The object API name must be appropriate for the use of the component. For example, if you include lightning-record-edit-form on a record page for an account, set object-api-name="Account". The component submits changes only if the record ID agrees with the specified object API name. If there's a mismatch, and the component includes lightning-messages, users see an error indicating the API name is invalid.

We strongly recommend importing references to objects and fields using the @salesforce/schema syntax especially when you plan to distribute your component as a managed package.

For example, create a form that enables users to edit the name field on a contact record page.

To display an editable field in the form, use the lightning-input-field component and set the field-name to the API name of the field. Labels for certain fields can differ from those displayed on a standard record page. For example, the Name field on the opportunity object displays "Name" instead of "Opportunity Name" while the Name field name on the account object displays "Account Name".

Although you can set the field name directly with the field-name attribute, we recommend that you import a reference to the name field. In this example, the form uses the object API name and record ID of the record page it's placed in.

To use your component in a managed package with your custom object, import the object using your namespace, for example, @salesforce/schema/namespace__object.

By importing the references, Salesforce verifies that the objects and fields exist, prevents objects and fields from being deleted, and cascades any renamed objects and fields into your component's source code. For more information, see Import References to Salesforce Objects and Fields.

For simplicity, the object API name and fields in the examples below are hardcoded in the templates. Note that passing in the object and fields using strings doesn’t provide compile-time validation. Use the @salesforce/schema imports to ensure the validity of your objects and fields.

This component doesn't support all Salesforce standard objects. This limitation also applies to a record that references a field that belongs to an unsupported object.

This component supports the Task object but Task.IsRecurrence and Task.IsReminderSet fields don't render even when requested.

This component supports the Event object but Event.IsRecurrence, Event.IsRecurrence2, and Event.IsReminderSet fields don't render even when requested.

External objects are not supported. The InformalName field is not supported for editing.

For a list of supported objects, see the User Interface API Developer Guide.

If you are working with an unsupported object or if have to use SOQL to query certain records, create your own UI and use Apex to work with Salesforce data. For more information, see Data Guidelines in the Lightning Web Components Developer Guide.

To enable record editing, pass in the ID of the record and the corresponding object API name to be edited. Specify the fields you want to include in the record edit layout using lightning-input-field. For more information, see the lightning-input-field documentation.

Include a lightning-button component with type="submit". When you press the Enter key or click the button, it validates the fields and submits the values.

To enable record creation, pass in the object API name for the record to be created. Specify the fields you want to include in the record create layout using lightning-input-field components. For more information, see the lightning-input-field documentation.

Include a lightning-button component with type="submit". When you press the Enter key or click the button, it validates the fields and submits the values.

lightning-record-edit-form renders the fields within the HTML form element and uses a button for form submission. Customizing the form element for form submission is not supported. We recommend that you use lightning-button with type="submit" as shown in the previous sections. The default type on lightning-button is button, which does nothing unless you include an onclick handler. If you use an HTML button element within lightning-record-edit-form, the default is type="submit".

When you submit the form, the component fires the custom events in this order.

• click if you use the onclick event handler on the button
• submit
• success or error

You can edit the field values programmatically using the onsubmit event handler or selectively handle any of the custom events. See Overriding Default Behaviors.

lightning-record-edit-form handles field-level validation errors and Lightning Data Service errors automatically. For example, entering an invalid email format for the Email field results in an error message when you move focus away from the field. Similarly, a required field like the Last Name field displays an error message when you leave the field blank and move focus away.

A Lightning Data Service error is returned when a resource becomes inaccessible on the server or an invalid record ID is passed in, for example. To display the error message automatically, include lightning-messages immediately before or after the lightning-input-field components. For more information, see Overriding Default Behaviors.

lightning-record-edit-form also verifies data input based on your validation rules. The form submits and saves data input only if all data in the fields are valid. The form clears validation rule errors when an onchange event is fired on the overall form, and also when you update a field with a validation rule error.

If a single field has multiple validation errors, the form shows only the first error on the field. Similarly, if a submitted form has multiple errors, the form displays only the first error encountered. When you correct the displayed error, the next error is displayed.

We recommend using custom validation rules to verify data input instead of implementing client-side validation errors. A validation rule can contain a formula or expression that evaluates the data in one or more fields. You can include an error message to display on an invalid field. See Validation Rules in Salesforce Help for more information.

A record Id is generated when a record is created successfully. To return the Id, use the onsuccess handler. This example shows an Id field that's populated when you create an account by providing an account name and pressing the Create Account button.

The record Id of the newly created account is assigned to the accountId property.

If your org uses record types, picklist fields display values according to your record types. You must provide a record type ID using the record-type-id attribute if you have multiple record types on an object and you don't have a default record type. Otherwise, the default record type ID is used.

To retrieve a list of record type IDs in your org, use the getObjectInfo wire adapter. For more information, see the getObjectInfo documentation.

Passing in a record type as a field on this component is not supported.

To create a multi-column layout for your record edit layout, use the Grid utility classes in Lightning Design System. This example creates a two-column layout.

To provide a custom field value when the form displays, use the value attribute on lightning-input-field. If you're providing a record ID, the value returned by the record on load does not override this custom value.

This example displays a form with a custom value for the account name field. The form creates a new account record when the button is clicked.

This example displays a form with a custom value for the account name field. The form updates the account record when the button is clicked.

Define the recordId and the objectApiName in your JavaScript code. The component inherits the record ID and object API name from the record page it's placed on.

To programmatically set the value when the form loads, provide your value in JavaScript. This example sets the value using the myValue property. You can set this value programmatically at a later time, as shown by the onclick event handler, which calls the overrideValue method.

The myValue property reassigned a new value when the Override Value button is clicked.

In the Salesforce user interface, the Display Density setting lets users choose how densely the content is displayed. The Comfy density shows labels on top of the fields and more space between page elements. Compact density shows labels next to the fields and less space between page elements.

The record form components, lightning-record-form, lightning-record-edit-form, and lightning-record-view-form, handle form density in similar ways. The density attribute is set to auto by default for all record form components.

Display density is supported for lightning-input-field and lightning-output-field within the form; display density is not supported for custom components within the form.

With auto density:

• Record form components detect the Display Density setting and the width of the form's container to determine label position. The record form components don't change the space between elements, however.
• If your Salesforce density setting is Comfy, the fields always display with their labels above them.
• If your Salesforce density setting is Compact, the fields initially display with their labels next to them. If you resize the form container below a certain width or use the form in a narrow container, the fields display with their labels above them. This behavior is similar to how other elements behave in Lightning Experience when Compact density is enabled. The record form components use the same width settings to determine when to switch the display density.
• If a record form component doesn't detect the Salesforce density setting, the fields display with their labels next to them. If you resize the form container to a narrow width, the fields display with their labels above them.

Detecting the user's density setting is only supported in Lightning Experience. When a record form component runs outside Lightning Experience, and density is set to auto, the fields display with their labels next to them, and switch to labels above the fields when in a narrow container.

If you specify a variant for lightning-input-field or lightning-output-field, the variant overrides the display density for that field.

To display a record form with a particular density, set the density attribute to one of these values.

• comfy makes the form always display labels on top of fields and doesn't detect the user setting.
• compact makes the form display labels next to their fields and doesn't detect the user setting. However, the form switches to the comfy density if the form is narrowed to the width that triggers the automatic change. To reduce the whitespace between the label and field when the form uses compact density, use the slds-form-element_1-col class on lightning-input-field or lightning-output-field.
• auto makes the form use the default behavior described in Form Display Density.

To customize the behavior of your form when it loads or when data is submitted, use the onload and onsubmit attributes to specify event handlers. If you capture the submit event and submit the form programmatically, use event.preventDefault() to cancel the default behavior of the event. This prevents a duplicate form submission.

Errors are automatically handled. To customize the behavior of the form when it encounters an error on submission or when data is submitted successfully, use the onerror and onsuccess attributes to specify event handlers.

Here are some example event handlers for onsubmit and onsuccess.

To see all the response data:

To reset the form fields to their initial values, use the reset() method on lightning-input-field.

We recommend creating a button that reverts the field values to their initial values using lightning-button. The default type for lightning-button is button, which does nothing unless you include an onclick handler.

If you use an HTML button element within lightning-record-edit-form to perform an action such as resetting the field values, specify type="button". By default, an HTML button element uses type="submit" when it's rendered in an HTML form element. Additionally, using type="reset" on a button deletes the form values and does not preserve the intial values.

This example creates a form with two fields, followed by Cancel and Save Record buttons. When you click the Cancel button, the handleReset method resets the fields to their initial values. Add this example to an account record page to inherit its record ID.

Call the reset() method on each field.

To reset the value of a specific field, first find the fields to reset using the class or name attribute.

This example uses the class attribute to assign a unique identifier to the Name compound field and Title field. It assumes that you created a custom class contactName.

Use querySelectorAll to query all fields matching the .contactName class.

If you are not using a custom class, use name instead. This example uses the name attribute to assign an identifier for the field to be reset to its initial value.

You can use the same name attribute values on multiple fields. Match the field name in the forEach block to trigger a reset on the email field.

To display a field conditionally, use the if:true|false directive. This example displays or hides the Name and Industry account fields when you select or unselect a checkbox.

The checkbox toggles between hiding and showing the fields using the onchange event handler.

A person account is a record type on the account object. It combines certain fields from the account and contact object into a single record. To use person accounts in your org, you must enable the Person Accounts setting first. After Person Accounts is enabled, it can’t be disabled. For more information, see Enable Person Accounts.

To access person account fields, use the account object with object-api-name="Account".

Specify the fields using the field names listed in the IsPersonAccountFields section for the Account object in the Object Reference.

The fields that begin with Person are the fields from the contact object.

For standard fields on the contact object, use Person<ContactFieldName>. For example, use field-name="PersonMobilePhone" for the MobilePhone field on the contact object.

For custom fields on the account object, use CustomFieldName__c as usual.

For custom fields on the contact object, use CustomFieldName__pc.

This example creates a form to update a person account record.

For more information, see Understand the Wire Service.

Multiple currencies aren't supported. If you enabled Activate Multiple Currencies in your org, lightning-record-edit-form displays currency fields using the corporate currency, even when the default currency of a record is different. For more information, see Manage Multiple Currencies.

Nesting lightning-record-edit-form in another instance of the component, or nesting it in lightning-record-form or lightning-record-view-form is not supported.

The form displays read-only input fields the same as output fields, without borders or gray backgrounds, unlike disabled input fields.

The Id field for a record ID displays as read-only even when specified with lightning-input-field.

Formula fields are automatically calculated, and displayed read-only on record forms. Formula fields always display the calculated value.

For more information about supported field types such as name fields and lookup fields, see the lightning-input-field documentation.

Use lightning-input-field only as a direct child of lightning-record-edit-form. Don't include lightning-input-field components in a template that an aura component composes.

The form displays read-only input fields the same as output fields, without borders or gray backgrounds, unlike disabled input fields.

Consider using the lightning-record-form component to create record forms more easily.

This component has usage differences from its Aura counterpart. See Base Components: Aura Vs Lightning Web Components in the Lightning Web Components Developer Guide.

error

The event fired when the record edit form returns a server-side error.

Use the event.detail property to return the error.

To display your error messages in the form, we recommend using lightning-messages as shown in the examples. lightning-messages can be used without a custom error event handler.

Include lightning-messages immediately before or after the lightning-input-field components to automatically display the string that's returned by message, and the detail or fieldErrors message if it's available.

The event properties are as follows.

load

The event fired when the record edit form loads record data. If you load the fields dynamically, load is fired before the child elements of lightning-record-edit-form finish loading. Consider the connectedCallback() lifecycle hook to perform initialization tasks. Alternatively, to load values or set properties dynamically, use a getter and setter instead.

load is fired when the form gets new data from Lightning Data Service, which can be once or multiple times after the component is initialized. For example, the load event is fired when:

• The record-id value changes
• The fields list changes
• The form includes picklist fields
• The record type changes

If you require the load event to be called only once, write code to prevent it from running more than once.

Use the event.detail property to return the record UI, and picklist values if you include picklist fields in the form.

The event properties are as follows.

submit

The event fired when the submit button is pressed. Client-side validation errors, if any, are displayed. The form is then submitted only when all fields in the form are valid. The form can be submitted only after it's loaded.

The submit event returns the following parameters.

The event properties are as follows.

success

The event fired when the record data is updated successfully. The load event then fires to return the updated data.

Use the event.detail property to return the saved record. For more information, see the User Interface API Developer Guide.

The event properties are as follows.

The LWC Recipes GitHub repository contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses lightning-record-edit-form, see the following components in the LWC Recipes repo.

• c-record-edit-form-dynamic-contact
• c-record-edit-form-static-contact

Work with Records Using Base Components

recordEditFormStaticContact example in lwc-recipes repository

recordEditFormDynamicContact example in lwc-recipes repository