Have you ever struggled to build your own custom component for finding and selecting Salesforce records? Well, we’re delighted to announce the solution you’ve been waiting for! The Lightning Record Picker is a new Lightning Web Component (LWC) that is highly configurable and addresses many platform needs, such as being mobile-friendly and offline-capable (thanks to GraphQL). The lightning-record-picker component enables anyone using an app on the Salesforce Platform to quickly and easily find and select Salesforce records.

The Record Picker component is already available in Beta as part of the Winter ’24 release, and will be Generally Available (GA) in Spring ’24. In this post, we’ll show you how to use lightning-record-picker in your custom LWC apps and experiences.

Meet the Record Picker

Think of the Record Picker as your go-to Lightning Web Component that can quickly find and select Salesforce records. You can integrate it into any experience that you envision; the Record Picker is designed to be generic and reusable across a wide range of use cases.

The Record Picker gives you the flexibility to directly configure its behavior and presentation. What’s more, it’s crafted with mobile users in mind. And, here’s an impressive feature: even if your mobile connection drops (we’ve all been there), it still works! How’s that possible? Credit goes to Salesforce’s secure offline record support paired with GraphQL to access offline data.

So, whether you’re on desktop or mobile, online or offline, the Record Picker has got your back.

Desktop

Mobile

Using the Record Picker is incredibly straightforward. To get started, just specify the object that you want to search. If needed, Record Picker provides you with the flexibility to configure the specific fields to use for retrieving and displaying results. But that’s not all — the Record Picker also offers extensive filtering capabilities to help you get the exact records needed for your use case.

Similarities with other components

lightning-input-field (see docs) looks quite similar to the Record Picker when it’s used for a lookup field, however, the two have distinct underlying mechanisms.

Although lightning-input-field is tailored for seamless integration with record forms, it offers limited customization options and has several constraints. These include: being governed by platform metadata specifically related to field relationships, supporting a limited set of entities, offering no control over matched fields, and having limited influence over displayed fields.

However, the lookup component rendered by lightning-input-field uses advanced SOSL-like matching capabilities (like finding “Dave” even if “Dove” was entered) and allows Salesforce Admins to set up Lookup filters. For the time being, the Record Picker performs queries akin to SOQL, which only supports exact text with wildcard matching.

Getting started with the Record Picker

lightning-record-picker is part of the base Lightning components (see Lightning Web Components Developer Guide), which means that you can use it easily, like any other LWC. We’ve crafted it to be user-friendly; here’s all you need to get started:

In this example, all we need to provide is the label to accompany the input field, the object to search, and a callback to handle the selection of a record.

Here’s what it looks like in the UI:

Providing a record ID to the value attribute makes the record picker component display a default selected record as shown in the screenshot below.

Exploring the Record Picker’s capabilities

We understand how crucial it is to tailor experiences to your users’ needs, so we’ve equipped the Record Picker with a host of customization options. We’ve outlined the main aspects here, but be sure to check out our developer docs and LWC Recipes with code samples, such as Record Picker Hello and Record Picker Dynamic Target, to get all the details.

The record picker component seamlessly integrates with your page, offering powerful features to enhance user interaction and data retrieval. It allows you to configure the default value, placeholder text, and error message — but that’s just scratching the surface. We’ve opened up new ways of customization and control, including:

• Matching fields: By default, we match an object’s Name field, but you can override this and use any field with a text or text formula field type, or you can even add a second field to use for matching.
• Display fields: Similarly, we only display the Name field to start with, but we’ve found that users love it when we add a secondary field to help them find the right record (especially when there are a lot of similarly named records).
• Filtering: You’ve got a whole lot of power and control over how the Record Picker filters records for your users, with comprehensive support for field types, operators, and custom logic to combine them. There’s also SOQL-like operator wildcards support.
• Validation: The Record Picker component supports validation to ensure data integrity and user input. Validation messages can be displayed when the component loses focus or when you use the reportValidity() method. You can also set custom validation messages using setCustomValidity().

Here’s a slightly more complex example showing the ease and flexibility of these customizations:

# recordPickerWithFilter.js

# recordPickerWithFilter.html

What lies ahead for the Record Picker?

Here are some ideas that we’re considering for future explorations with the Record Picker:

• Advanced querying capabilities: The Record Picker could offer advanced querying capabilities, such as SOSL (Salesforce Object Search Language), to provide users with powerful search options. In addition, we also imagine letting users inject their own custom data source to search for records.
• Platform actions integration: Users could use platform actions, such as Create New or object-specific quick actions, directly within the Record Picker, making the process of creating and interacting with records more efficient.
• Most recently used records (MRUs): This would display a user’s most recently accessed records, and when integrated into the record picker results, it could ensure quick access to frequently used items.
• Dynamic Target Object mode: This mode could allow users to choose records from different target objects.
• Multi-Select mode: The Record Picker could support multi-select mode, enabling the selection of multiple records at once.

We invite you to help us define the future of the Record Picker! If these features (or others) are important to you, we’d love to hear your feedback so we can prioritize them. Feel free to reach out to us on the Trailblazer Community using the #Lightning-record-picker tag.

Conclusion

You’ve now had a taste of what the record picker component is and what it can do with it. It’s your LWC of choice when you simply want to find a record with maximum flexibility around what fields to match and display, as well as run-time customizable filters. And if you need to search for records on mobile or while offline, then the Record Picker is your best bet.

Don’t forget to explore the sample code (Record Picker Hello, Record Picker Dynamic Target) and additional resources below.

Further resources

• Record Picker in Lightning Web Component library
• Record Picker components within LWC Recipes:
  • Record Picker Hello
  • Record Picker Dynamic Target
• Lightning Data Service
• GraphQL Wire Adapter for LWC
• Briefcase Builder
• Trailhead: Search Solution Basics
• Explore the GraphQL Wire Adapter, Now in Beta

About the authors

Eric Constantin is a Principal Member of Technical Staff at Salesforce, specializing in Search. He recently focused his efforts on the architecture and development of the new record picker component. Outside of work, you might find Eric going up or down mountains in his pursuit of adventure sports.

Antoine Rosenbach is a Lead Software Developer on the Search team at Salesforce. Outside of coding, he transforms into a jazz musician, switching between the piano keys and his trombone. 🎶

Simon Kempf is a Software Developer at Salesforce working on the Search team and contributing to the Salesforce Platform. Outside of coding, he is a mountains enthusiast always on the lookout for new hiking trails, and loves skiing during the winter season.

Rami Noufal is a Software Developer at Salesforce working in the Search team and contributing to the Salesforce Platform. When not coding, he enjoys playing and watching tennis.

Thomas Foulon is a Software Developer at Salesforce working on the Search team. When not coding, he enjoys playing video games and music on the piano.

Aurélie Merlin is a Senior Manager at Salesforce managing a software engineering team that provides Search UI components, such as Lookup and Record Picker. In her leisure time, she’s a board game enthusiast who enjoys puzzles.