SfSkills Domains Docs GitHub

Home / lwc / experience-cloud-search-customization

experience-cloud-search-customization

Use this skill when configuring or extending search on an Experience Cloud site — covering Search Manager scope configuration, LWR vs Aura search component selection, federated search setup, guest user search access, and custom search result components. NOT for SOSL/SOQL query development — use lwc/experience-cloud-lwc-components.

Open the skill folder on GitHub

Experience Cloud Search Customization

Use this skill when a practitioner needs to configure, extend, or troubleshoot search behavior on an Experience Cloud site — including controlling which objects appear in results, enabling federated search against external endpoints, selecting the right standard search components for the site template type, or diagnosing guest user search visibility problems.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

Search Manager and Search Scope

Every Experience Cloud site has a Search Manager accessible from Experience Builder > Search. The Search Manager controls:

Objects must satisfy two requirements before they can be added to Search Manager scope: (1) the object must have "Allow Search" enabled in Setup, and (2) the object must have at least one field indexed for search. If an object does not appear in Search Manager's available objects list, check both of these prerequisites.

Search scope is per-site. The same object can have different search visibility on different sites in the same org.

LWR vs Aura Search Components

Salesforce provides separate standard search components for each site template type:

TemplateStandard search componentWhere it lives in Experience Builder
Aura sites (legacy)Search component (Aura-based)Components > Search
LWR sitesSearch Results and Search Bar components (LWC-based)Components panel

These components are NOT interchangeable. Dropping the Aura Search component into an LWR page will silently fail or not render. Dropping the LWR Search Results component into an Aura site is not supported. Confirm the site template type first; then select only the matching component.

For LWR sites, Salesforce also supports building a fully custom search result component using the lightning/uiSearchApi wire adapter (available in API 55+), which allows custom result layouts without replacing the underlying search index.

Federated search allows an Experience Cloud site to send the user's search query to an external HTTP endpoint and merge the external results with native Salesforce results in a single result set. Key mechanics:

Guest User Search and Secure Guest User Record Access

Guest users (unauthenticated site visitors) execute all queries under a shared Guest User record. Two layers control what they can see in search results:

  1. Object-level sharing: The Guest User profile must have read access on the objects being searched. Org-wide defaults for those objects must permit guest access, or sharing rules must explicitly grant it.
  2. Secure Guest User Record Access (org setting in Setup > Sharing Settings): When this setting is enabled — and Salesforce has been gradually enforcing it as the default — guest users can only see records they own or that are explicitly shared with the Guest User via sharing rules. Records that authenticated users can see through role hierarchy or manual sharing are NOT automatically visible to guests. Enabling this setting can silently break previously working guest search results.

These two layers are independent. A guest user with object read permission but no record-level sharing access will see zero search results for that object with no error message.

Common Patterns

Pattern: Knowledge-Only Search Scope

When to use: A self-service portal where site visitors should search only Salesforce Knowledge articles, not Cases, Contacts, or other internal objects.

How it works:

  1. In Experience Builder, open the Search Manager.
  2. Remove all objects except Knowledge from the searchable objects list.
  3. Ensure the Knowledge object has IsVisibleInPkb = true for published articles and that Guest User data category visibility is configured (see lwc/knowledge-article-lwc for data category details).
  4. Place the appropriate search component for the site template (Aura Search or LWR Search Bar + Search Results).
  5. If promoted terms are needed, configure them in Search Manager > Promoted Search Terms.

Why not the alternative: Leaving all objects in scope exposes Cases, Contacts, and custom objects in search results. Guest users who lack sharing access will see zero results for those objects, but authenticated site members may see records the business did not intend to expose. Scoping to Knowledge alone eliminates this risk.

Pattern: Federated Search Combining Salesforce and External Knowledge Base

When to use: A portal where users should see results from both Salesforce Knowledge and an external knowledge base or document management system in a single search experience.

How it works:

  1. Build or deploy an external HTTP endpoint that implements the Salesforce Federated Search specification. The endpoint must accept a POST request with the query payload and return results in the required JSON schema.
  2. In Setup > Federated Search, register the endpoint URL and any required authentication (Named Credential or API key header).
  3. In Experience Builder > Search Manager, enable the federated search source for the site.
  4. (Optional) Create a custom federatedSearchResult LWC to control the layout of external results in the result list.
  5. Test the integration by running a search that matches known content in the external system and confirming both Salesforce and external results appear in the merged result set.

Why not the alternative: Replicating external content into Salesforce as CMS content or Knowledge articles to enable native indexing is valid but creates data duplication and synchronization overhead. Federated search avoids duplication by querying the external system at search time.

Decision Guidance

SituationRecommended ApproachReason
Site built on LWR template, need standard search UIUse LWC Search Bar + Search Results standard componentsAura search component is not supported on LWR pages
Site built on Aura template, need standard search UIUse Aura Search standard componentLWR search components are not available in Aura sites
Need custom result card layout on LWRBuild custom LWC using lightning/uiSearchApi wire adapterAllows custom layout while retaining the native search index and scope
Guest users not seeing expected records in searchCheck Secure Guest User Record Access setting + guest sharing rulesThis setting overrides object-level permissions and silently returns zero results
Merging external content into site searchFederated search via Setup > Federated Search + external endpointAvoids data duplication; real-time query to external system
Restricting which objects appear in searchConfigure Search Manager scope in Experience BuilderPer-site control; does not affect other sites or the internal app
Promoting specific records for key termsUse Promoted Search Terms in Search ManagerDeclarative; no custom code required

Step-by-step instructions for an AI agent or practitioner working on this task:

  1. Confirm site template type and search requirements: Identify whether the site is LWR or Aura. Determine the target objects for search, whether guests need access, and whether federated (external) search is required. Document the Secure Guest User Record Access setting value from Setup > Sharing Settings.
  2. Configure Search Manager scope: In Experience Builder > Search, add only the objects that should appear in results. Verify each object has "Allow Search" enabled in Setup > Object Manager and has at least one searchable field. Remove objects that should not be exposed to site visitors.
  3. Place the correct search component: For LWR sites, place the Search Bar component in the header region and the Search Results component on the search results page. For Aura sites, use the Search component. Do not mix components across template types.
  4. Configure guest user access if required: Enable the Guest User profile's object-level read permission for each searchable object. Create sharing rules or set OWDs to make relevant records accessible to guests. Validate under the Secure Guest User Record Access setting's current state.
  5. Set up federated search if required: Register the external endpoint in Setup > Federated Search, validate the endpoint responds within the timeout, enable it in Search Manager, and test with a cross-system query. Build a custom federatedSearchResult LWC if a non-default result layout is needed.

Review Checklist

Run through these before marking work in this area complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. LWR and Aura search components are not interchangeable — The Aura Search component does not render on LWR pages; the LWR Search Bar/Search Results components are not available in Aura sites. Dropping the wrong component type produces no error in Experience Builder but results in a broken or empty search experience at runtime.
  2. Secure Guest User Record Access silently removes search results — When this org setting is enabled (the Salesforce-enforced default going forward), guest users see only records they own or that are explicitly shared with the Guest User via sharing rules. A guest search against an object with OWD set to Public Read Only still returns zero results if no sharing rule exists, because the setting overrides the OWD for guests. No error is thrown.
  3. Object missing from Search Manager does not produce an error — If a searchable object is absent from the site's Search Manager scope, search queries simply never return results for that object. There is no warning in the UI or in the search response. This is easily confused with a permissions or indexing problem.
  4. Federated search requires the external endpoint to handle the callout — Salesforce's search infrastructure makes the outbound HTTP request to the external endpoint. There is no Apex @future or Queueable involved. If the endpoint is behind a firewall, IP allowlisting for Salesforce's outbound IP ranges is required. A timeout or non-200 response from the external endpoint silently suppresses the external results without surfacing an error to the end user.
  5. Admin Experience Builder preview does not replicate guest sharing — Testing search as an administrator in Experience Builder preview bypasses all sharing restrictions. Records that appear in the admin preview may be invisible to actual guest users. Always validate guest search behavior in an incognito browser session against the live or preview site URL.

Output Artifacts

ArtifactDescription
Search Manager configurationPer-site object scope, promoted terms, and filter fields configured in Experience Builder
Guest user sharing checklistDocumented OWD values, sharing rules, and Secure Guest User Record Access setting state for each searchable object
Federated search endpoint specExternal endpoint URL, authentication configuration, and result schema mapping registered in Setup
Custom federatedSearchResult LWC(Optional) Custom result card component for non-default federated result layouts
Custom search LWC using lightning/uiSearchApi(Optional) Fully custom search UI for LWR sites that need non-standard result rendering

Package files