How To Query Files And Display Using Lwc Component
Querying and rendering Salesforce files within a Lightning Web Component requires coordinating a server-side Apex controller with client-side reactive JavaScript properties and the native lightning-file-card layout. Implementing this architecture efficiently depends on executing SOQL queries against ContentDocumentLink and ContentVersion objects while respecting Lightning platform security and sharing constraints.
Pre-Requisites and Architecture Planning
- Building a secure, high-performing file display interface requires careful mapping of object relationships, user permissions, and component data flow before writing code.
- Essential gear/tools/materials: Salesforce Developer Edition or Enterprise Org, Visual Studio Code with Salesforce Extension Pack, Salesforce CLI (sfdx), and a profile with access to ContentDocument and ContentVersion objects.
- Mandatory prerequisite knowledge/standards: Proficiency in asynchronous JavaScript (Promises/Async-Await), familiarity with Lightning Data Service (LDS), understanding of Salesforce sharing rules regarding file visibility, and basic Apex SOQL syntax for library management.
- Estimated budget/duration benchmarks: Zero software licensing cost utilizing standard developer tooling; estimated implementation and testing time is two to four hours for an experienced developer.
Step-by-Step Implementation Workflow
Step 1: Create the Server-Side Apex Controller
- Write an Apex class annotated with with sharing to enforce security policies and retrieve file metadata linked to a specific parent record ID.
- Define an @AuraEnabled method that accepts a record ID parameter and executes a SOQL query fetching ContentDocumentId, Title, FileExtension, and ContentSize from the ContentDocumentLink object where the LinkedEntityId matches the target record.
- Wrap the query execution block in a try-catch statement to gracefully handle null inputs, missing parent records, or database exception errors before returning the list of file wrapper records to the client.
Pro-Tip: Always query through the ContentDocumentLink junction object rather than querying ContentDocument directly to ensure you respect record-level sharing and context user visibility.
Step 2: Build the Lightning Web Component JavaScript Controller
- Import the Apex method created in the previous step into your Lightning Web Component JavaScript file using standard scoped module imports from @salesforce/apex.
- Use the wire service decorator or imperative JavaScript promises to call the Apex method, passing the record ID as a dynamic parameter whenever the component initializes or changes context.
- Store the returned file records array inside a tracked or reactive JavaScript property to ensure the component template re-renders automatically upon data resolution.
Warning: Avoid passing unescaped or unvalidated string parameters directly into dynamic SOQL queries in your Apex controller to prevent injection vulnerabilities.
Step 3: Design the HTML Template Structure
- Construct the component template HTML markup using iterative looping directives like for:each paired with for:item to iterate through the reactive array of retrieved file records.
- Embed the native lightning-file-card component inside the iteration block, passing the individual file's ContentDocumentId to the file-id attribute for automatic thumbnail generation and preview handling.
- Add conditional rendering directives using template if:true to display a clean notification message or empty state illustration when the file list array evaluates to zero records.
Step 4: Configure the Component Meta XML File
- Update your component metadata configuration file to explicitly expose the Lightning Web Component to record page target environments by adding lightning__RecordPage as a supported target.
- Configure target configs to accept the recordId object property so the host page automatically feeds the current record context into your component without manual ID hardcoding.
- Deploy the updated source code bundle to your target Salesforce sandbox or scratch org using the Salesforce CLI deployment command.
How to — Display Accounts in map using Lightning Map | LWC | Salesforce ...
Technical Parameters and Query Comparison
| Object Name | Primary Field Purpose | Security Implication | Performance Impact |
|---|---|---|---|
| ContentDocumentLink | Connects files to records (accounts, cases, custom objects) | Enforces sharing rules based on LinkedEntity access | Low overhead when indexed by LinkedEntityId |
| ContentVersion | Stores actual file binary data, titles, and extensions | Inherits permissions from parent ContentDocument | Moderate overhead if querying binary body fields |
| ContentDocument | Manages master document metadata and deletion states | Global read access based on active document links | Low overhead for title and extension retrieval |
Common Site Failures and Field Fixes
- Root Cause: Files fail to appear in the component interface despite successful file uploads on the parent record.
- Actionable Fix: Verify that the user executing the query possesses read access to the ContentDocumentLink object and that sharing rules permit visibility of the linked library items.
- Root Cause: The component throws an undefined property error upon initial page load.
- Actionable Fix: Ensure your JavaScript controller handles asynchronous timing gaps by checking for null or undefined data arrays before attempting iteration loops in the HTML template.
- Root Cause: Lightning file cards render broken image icons or missing previews.
- Actionable Fix: Confirm that the ContentDocumentId passed into the file-id attribute matches an active, non-deleted file record within the same org instance.
Frequently Asked Questions
Can I query files across multiple parent records in a single component?
Yes, by modifying your Apex SOQL query to accept a list of parent IDs or by executing a parent-to-child subquery through the ContentDocumentLink relationship, though you must account for governor limits on query rows and execution time.
How do I restrict file types displayed in my LWC component?
You can filter the files directly in your Apex SOQL query by adding a condition to the FileExtension field, such as checking for pdf, png, or jpg formats before returning the results to the client.
Is it better to use the wire service or imperative Apex for file retrieval?
The wire service is ideal for reactive data binding when the record ID is immediately available upon component load, while imperative Apex is preferred when you need to trigger the query based on user interaction or complex conditional logic.
How do users preview files directly from the lightning-file-card?
The native lightning-file-card component includes built-in event handlers that automatically launch the standard Salesforce modal file preview player when a user clicks on the file thumbnail or title.
Streamline your Salesforce user experience today by deploying high-performance Lightning Web Components designed to surface critical document assets directly where your teams work.
