ViewerFilesSwiper Configuration Reference
Use this ViewerFilesSwiper configuration reference to set up a Salesforce files carousel in Lightning App Builder and Flow screens. Learn how to configure layout, navigation, autoplay, filtering, and Flow actions so users can browse related ContentDocument / ContentVersion files in the right way for each use case.
Overview
The ViewerFilesSwiper component helps you present related files in a modern, interactive swiper UI. You can:
- Control layout and effects - Configure direction, transition style, visible slide count, and spacing
- Improve navigation - Enable arrows, pagination, keyboard control, and rewind behavior
- Automate playback - Turn on autoplay and tune delay in milliseconds
- Filter records - Narrow file lists with SOQL filter fragments and picklist-based dropdown filtering
- Add user actions - Let users upload files or launch a Screen Flow with
recordId
Visual & Layout Settings
Control how the carousel looks and arranges its items.
| Parameter | Type | Default | Description |
|---|---|---|---|
| Direction | Picklist | Horizontal | Determines slide movement direction. Options: Horizontal (left/right) or Vertical (up/down). |
| Effect Type | Picklist | Normal | Transition effect between slides. Normal: standard sliding animation. Fade: cross-fade between slides (best for single-slide views). Grid: arranges slides in a grid layout (usually combined with higher Slides Per View). |
| Slides Per View | Integer | 1 | Number of slides visible at the same time. Use 1 for a single hero preview, or 3–4 for thumbnail-like browsing. |
| Space Between | Integer | 10 | Distance in pixels between slides. Example: 10 = tight layout, 24 = more visual separation. |
| Display Field | String | (Empty) | API name of a field on ContentVersion (for example Title or Description) shown as a caption overlay. If empty, no caption is rendered. |
Navigation & Interaction
Configure how users move through slides.
| Parameter | Type | Default | Description |
|---|---|---|---|
| Enable Navigation | Boolean | False | Shows previous/next arrow controls. |
| Enable Pagination | Boolean | False | Shows pagination indicators (dots). |
| Enable Pagination Fraction | Boolean | False | Switches pagination from dots to fraction format (for example 1 / 5). Requires Enable Pagination. |
| Enable Keyboard | Boolean | False | Enables left/right keyboard navigation when the component has focus. |
| Enable Rewind | Boolean | False | Returns to the first slide after the last slide (and reverse direction when navigating backwards). |
Autoplay Settings
Automate slide progression.
| Parameter | Type | Default | Description |
|---|---|---|---|
| Enable Autoplay | Boolean | False | Automatically advances to the next slide. |
| Autoplay Delay | Integer | 1000 | Delay in milliseconds before moving to the next slide. Numeric examples: 1000 = 1 second, 3000 = 3 seconds, 5000 = 5 seconds. |
Data & Filtering
Control which files are included in the swiper.
| Parameter | Type | Default | Description |
|---|---|---|---|
| Additional Filter | String | (Empty) | SOQL WHERE clause fragment to filter ContentVersion records. Examples: FileType = 'PDF', Title LIKE '%Contract%', ContentSize > 10000. |
| Filter API Name | String | (Empty) | API name of a Picklist field on ContentVersion. When set, the component shows a dropdown to filter files by that picklist’s values (for example Category__c). |
| Sub Query | String | (Empty) | Advanced option: full SOQL subquery used to fetch related records instead of standard attached files. Useful for showing files from related objects. |
Actions & Flow Integration
Add optional action buttons in the component header.
| Parameter | Type | Default | Description |
|---|---|---|---|
| Enable Add File | Boolean | False | Shows an Add Files button for file upload to the current record context. |
| Flow API Name | String | (Empty) | API name of a Salesforce Screen Flow. When set, a button launches that flow in a modal and passes recordId as input. |
| Flow Button Label | String | (Empty) | Label text for the Flow launch button. If empty, the default label is Run Flow. |
Configuration Tips
- Performance: Large batches of high-resolution files can slow initial rendering. Use Additional Filter to narrow scope.
- Mobile layout: For smaller regions, reduce Slides Per View to improve readability and interaction.
- Security modes: ViewerFilesSwiper is designed to run in Lightning security modes (Locker/LWS).
Common Use Cases
How do I configure ViewerFilesSwiper for a single large preview?
Set Slides Per View to 1, keep Direction as Horizontal, and optionally use Effect Type = Fade for a clean single-file transition.
How do I show multiple files at once like a thumbnail strip?
Set Slides Per View to 3 or 4, adjust Space Between (for example 10 or 24), and enable Navigation so users can move through groups of files quickly.
How do I filter the carousel to only show specific files?
Use Additional Filter with a SOQL WHERE fragment such as FileType = 'PDF' or Title LIKE '%Contract%'.
How do I let users filter by category from a dropdown?
Set Filter API Name to a picklist field on ContentVersion (for example Category__c) so users can choose values directly from the component UI.
How do I launch a Flow from the swiper?
Set Flow API Name and optionally Flow Button Label. The component shows a button and passes the current recordId into the Screen Flow.
Related Topics
- Retrieve Data Using Apex Code with Viewer - Use Apex data retrieval patterns for advanced Viewer scenarios.
- Creating Documents in Salesforce Using Apex - Generate documents from Apex-driven business logic.
- How to Use Template Filter - Add filter-driven behavior in Viewer processes.
- Digital PDF Signing - Add signing workflows to generated PDF outputs.