Record Picker

The lightning-record-picker component enables you to search for a list of Salesforce records that match search input.

It uses the GraphQL wire adapter to search for records, displays the records, and enables you to select a record.

This example creates a record picker component that searches for Account objects.

1<lightning-record-picker
2    label="Accounts"
3    placeholder="Search Accounts..."
4    object-api-name="Account"
5>
6</lightning-record-picker>

lightning-record-picker implements the autocomplete combobox (lookup) blueprint in the Salesforce Lightning Design System (SLDS). The combobox adapts to SLDS 1 or SLDS 2 styling based on the org’s theme or the container app that you use.

The filter attribute specifies which records the component lists in the record picker. The value for filter is an object with a criteria property and an optional filterLogic property. The value for criteria is an array with a list of filter criteria objects.

This example filters records where the Website field equals “https://www.grenoble.fr” or null, the Name of the related Parent doesn’t start with “Acme”, and Type doesn’t equal “Partner”.

1filter = {
2  criteria: [
3    {
4      fieldPath: "Website",
5      operator: "eq",
6      value: "https://www.grenoble.fr",
7    },
8    {
9      fieldPath: "Website",
10      operator: "eq",
11      value: null,
12    },
13    {
14      fieldPath: "Type",
15      operator: "ne",
16      value: "Partner",
17    },
18    {
19      fieldPath: "Parent.Name",
20      operator: "like",
21      value: "Acme%",
22    },
23  ],
24  filterLogic: "(1 OR 2) AND NOT(4) AND 3",
25};

1<lightning-record-picker
2    object-api-name="Account"
3    label="Accounts"
4    filter={filter}>
5</lightning-record-picker>

To define logic for the set of filter criteria objects in the criteria array, specify the filterLogic property in the filter object. If filterLogic is undefined, all criteria apply with an AND logical operator by default. Valid operators are AND, OR, and NOT. The AND operator has higher precedence than OR. Parentheses are supported.

The example in Specify a Filter shows how to use filterLogic.

The filter object defines the criteria for individual filters. You can combine these filters by using logical operators that you specify with the filterLogic property.

The filter object requires these properties for each element in the criteria array.

The like operator works similarly to the SOQL like operator, with % and _ wildcards. The % wildcard matches zero or more characters. The _ wildcard matches exactly one character.

For date types (Date, DateTime, and Time), value is passed as an object with either a value or literal property. Use value if referring to an absolute date, time, or datetime. Use literal if referring to a relative date or time.

A value must be passed as a string (not a JavaScript date) that corresponds to the type of field. Use the JavaScript methods in the following table to convert to the correct format. The API throws an error if the date format is incorrect.

This example uses a Date value to filter results to a specific date.

1filter = {
2  criteria: [
3    {
4      fieldPath: "LastModifiedDate",
5      operator: "gt",
6      value: { value: new Date("2024-01-01").toISOString() },
7    },
8  ],
9};

A literal is a date literal that represents a relative range of time, such as last month, this week, or next year. The value for literal must be a value from the GraphQL API list of Literal Values for Relative Dates.

The following example uses the TODAY literal to filter results to today’s date.

1filter = {
2  criteria: [
3    {
4      fieldPath: "LastModifiedDate",
5      operator: "lt",
6      value: { literal: "TODAY" },
7    },
8  ],
9};

To customize the way record suggestions appear in the record picker, use the display-info attribute. The display-info attribute references an object that specifies the main field and an additional field to display. By default, the value of the name field of the target object is displayed.

This example sets the primary field to the name of the related account and adds Title as a display field in the returned record picker results.

1displayInfo = {
2  primaryField: "Account.Name",
3  additionalFields: ["Title"],
4};

1<lightning-record-picker
2    object-api-name="Contact"
3    label="Contacts"
4    display-info={displayInfo}>
5</lightning-record-picker>

The display-info referenced object (displayInfo in the example) has the following properties. One or both properties are required if using display-info. Cross-object fields such as Account.Name are supported for both primaryField and additionalFields.

By default, the search is conducted on the name field of the target object. To look for a match to a different field or additional fields, specify the matching-info attribute. The matching-info attribute references an object that defines which fields to query for the search terms in the record picker.

Cross-object fields such as Account.Phone are supported.

The matching-info referenced object (matchingInfo in the example) has the following properties. One or both properties are required if using matching-info.

You can specify a matching mode for both the primary field and the additional fields using the mode property as shown in the following example. Specifying a matching mode can be useful in addressing performance concerns when searching through large datasets within an org.

The mode property accepts two values:

• startsWith: matches results that start with the search term
• contains: (default) matches results that contain the search term

This example shows a matchingInfo config that queries records whose Name field starts with the search term or whose Phone field contains the search term.

1matchingInfo = {
2  primaryField: { fieldPath: "Name", mode: "startsWith" },
3  additionalFields: [{ fieldPath: "Phone" }],
4};

1<lightning-record-picker
2    object-api-name="Contact"
3    label="Contacts"
4    matching-info={matchingInfo}>
5</lightning-record-picker>

The event fired when a record has been selected or cleared.

The change event returns the following parameter.

The event properties are as follows.

The event fired when Lightning Data Service returns an error.

The error event returns an object with these parameters.

The event properties are as follows.

The event fired when the focus is set.

The event fired when the focus is removed.

The event fired when the component stops loading and is rendered. To call a method on the component, use the ready event. For example, you can call this.template.querySelector('lightning-record-picker').focus(); by using this event to put focus on the component after it finishes rendering.

lightning-record-picker can return blocking and non-blocking errors. When a blocking error occurs, the input is disabled and a red message appears. To handle these errors, change the component configuration to exit the blocking error state based on what specific error was thrown.

When a non-blocking error occurs, a red message appears but the user can still interact with the component. The user must change their search or reload the page to exit the non-blocking error state.

The following is a list of errors emitted by the lightning-record-picker component.

Validation messages display when the component loses focus or when the component uses the reportValidity() method. Validation messages also display when a user types a search term but doesn’t select a record, or the component is required and the user doesn’t select a record.

Set a custom validation message with the setCustomValidity() method. Setting a message puts the component in an invalid state. The custom message isn’t automatically displayed. Call reportValidity() to display the custom message.

The lightning-record-picker component only supports objects in the User Interface API with at least one name field as part of the nameFields array from the getObjectInfo response.

The fields that are displayed for the records may not be an exact match for the records returned by the API. The displayed record fields are determined by the primaryField and additionalFields properties set for display-info. If the matching-info properties are set to record fields that aren’t used by display-info, the displayed records can confuse users because the matching fields aren’t displayed.

When you search for results with a search term, wildcards characters (’%’ and ’_’) are escaped in the search term.

lightning-record-picker doesn’t support searching on encrypted fields, including encrypted fields configured in the matching-info attribute.

When configuring the primaryField property of the display-info attribute, we recommend that you pick a field that’s marked as required in the sObject definition. Using a required field prevents displaying a blank selection when a record is selected.

lightning-record-picker uses GraphQL wire adapter and inherits any GraphQL limitations. For more information, see GraphQL Known Limitations.

When working with a public method on lightning-record-picker, make sure the component is fully rendered before calling the method. Don’t call focus() from renderedCallback() as the component and its child components may not be fully rendered. For example, you can call the public method using the ready event instead.

1<lightning-record-picker
2  label="Choose a Record"
3  placeholder="Search Contacts"
4  object-api-name="Contact"
5  onready={handleOnReady}
6></lightning-record-picker>

In your JavaScript file, set the focus on the record picker. This example assumes that you have only one lightning-record-picker component on the page.

1handleOnReady(){
2    this.template.querySelector('lightning-record-picker').focus();
3 }

Alternatively, use the lwc:ref directive with the ready event to locate the component.

1<lightning-record-picker
2  lwc:ref="recordPicker"
3  label="Choose a Record"
4  placeholder="Search Contacts"
5  object-api-name="Contact"
6  onready={handleOnReady}
7></lightning-record-picker>

1handleOnReady(){
2    this.refs.recordPicker.focus();
3 }

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-picker, see the c-record-picker-* components in the LWC Recipes repo.