Handoff Image Module
Overview
The Handoff Image module displays images from SCF (Secure Custom Fields) or ACF Pro Flexible Content sub-fields. It automatically binds to the current Flexible Content layout context, making it easy to output dynamic images without manual configuration.
Use the Handoff Image module when you need automatic field binding within a Flexible Content layout. For standard Divi modules, you can still use Dynamic Content to pull images from SCF/ACF fields.
When to use it
Use the Handoff Image module when:
- You need to display an image from a Flexible Content sub-field
- You want automatic context binding without selecting dynamic content manually
- You need to set dynamic width and height from additional fields
- You want images that respect the current layout row context
Use a standard Divi Image module with Dynamic Content when:
- You need more advanced image options not available in the Handoff module
- You're working outside of a Flexible Content context
- You need link or lightbox features
Content Tab
This is where all the functional settings for the Handoff Image module live.
Main Settings
Configure which field provides the image content.
SCF/ACF Pro Field: Select the image field to display.
Choose a field from either SCF or ACF Pro to display content within the module. The dropdown lists all available sub-fields from the current Flexible Content layout.
Supported field types:
- Image – Standard image field (supports URL, ID, or array return formats)
- File – File upload field (displays if the file is an image)
- Gallery – Displays all images in the gallery
- Text/URL – Displays the image if the value is a valid image URL
Background
Standard Divi background options are available for the module container.
Design Tab
The Design tab contains all visual styling options for the Handoff Image module.
Sizing
Standard Divi sizing controls including width, max-width, height, and alignment.
SCF/ACF Size Fields
Control image dimensions dynamically using values from SCF or ACF fields.
Image Width Field: Set the image width from a field value.
Select an SCF or ACF field to define the image width. Leave blank to use the default width setting from the Sizing options.
The field should contain a valid CSS width value (e.g., 300px, 50%, 100vw).
Image Height Field: Set the image height from a field value.
Select an SCF or ACF field to define the image height. Leave blank to use the default height setting from the Sizing options.
The field should contain a valid CSS height value (e.g., 200px, auto).
Maintain Aspect Ratio: Preserve proportions based on field values.
Enable to maintain the aspect ratio based on the selected SCF or ACF field value. When enabled, the image scales proportionally rather than stretching.
Additional Design Options
The following standard Divi design options are available:
| Section | Description |
|---|---|
| Spacing | Margin and padding controls |
| Border | Border style, width, color, and radius |
| Box Shadow | Shadow effects for the module |
| Filters | CSS filter effects (blur, brightness, contrast, etc.) |
| Transform | Scale, rotate, skew, and translate transformations |
| Animation | Entry animation effects |
Advanced Tab
The Advanced tab provides standard Divi positioning and visibility controls.
| Section | Description |
|---|---|
| Visibility Settings | Control visibility on different devices and for logged-in users |
| Transition | Configure transition effects for hover states |
| Position Settings | Set position type (relative, absolute, fixed) and z-index |
| Scroll Settings | Configure scroll-based effects and sticky positioning |
Settings Reference
| Setting | Location | Type | Default | Description |
|---|---|---|---|---|
| SCF/ACF Pro Field | Content → Main | Select | none | The sub-field containing the image |
| Image Width Field | Design → SCF/ACF Size Fields | Select | - | Optional field for dynamic width |
| Image Height Field | Design → SCF/ACF Size Fields | Select | - | Optional field for dynamic height |
| Maintain Aspect Ratio | Design → SCF/ACF Size Fields | Toggle | Off | Preserve image proportions |
Supported Field Types
The Handoff Image module intelligently handles different SCF/ACF field types and return formats:
Image Field
| Return Format | Handling |
|---|---|
| URL | Displays the image directly from the URL |
| ID | Retrieves the image URL from the attachment ID |
| Array | Extracts the URL from the array data |
File Field
| Return Format | Handling |
|---|---|
| URL | Displays if the file is an image type |
| ID | Retrieves and validates as image |
| Array | Extracts URL and validates as image |
Gallery Field
Displays all images in the gallery when the image source field is a gallery field.
Text/Textarea/URL Fields
If the field value is a valid image URL, it displays the image. Useful for simple URL-based image storage.
Alt Text Handling
The module automatically generates alt text for accessibility:
- Attachment caption – Uses the image caption if available
- Filename fallback – Extracts the filename (without extension) as alt text if no caption exists
Examples and Common Patterns
Example 1: Team Member Photo
Display a team member's photo from a Flexible Content layout:
- Add a Handoff Image module to your Divi Handoff Layout
- In Content → Main, set SCF/ACF Pro Field to your photo field (e.g.,
member_photo) - Style the image using Design → Border to add rounded corners
- The image automatically displays the photo for each team member
Example 2: Hero Image with Dynamic Sizing
Create a hero section with a dynamically sized image:
- Create SCF/ACF fields for
hero_image,hero_width, andhero_height - Add a Handoff Image module
- Set SCF/ACF Pro Field to
hero_image - In Design → SCF/ACF Size Fields:
- Set Image Width Field to
hero_width - Set Image Height Field to
hero_height - Enable Maintain Aspect Ratio
- Set Image Width Field to
Example 3: Product Feature Image
Display product images within a repeater:
- Inside a Handoff Repeater module, add a Handoff Image module
- Select the image sub-field from the repeater row
- The module automatically uses the correct image for each repeater iteration
Pitfalls and Limits
Field not showing? Make sure the SCF/ACF field is a sub-field of the Flexible Content layout that the Divi Handoff Layout is mapped to. The module only sees fields within its layout context.
Limitations:
- No link options – Unlike the standard Divi Image module, the Handoff Image doesn't include built-in link or lightbox functionality. Wrap it in a link module if needed.
- Builder preview requires saved content – The module fetches image URLs via REST API, so field data must be saved before it appears in the visual builder.
Tips
- Use image field type when possible for best results, as it properly handles different return formats
- Set return format to URL in SCF/ACF for simplest configuration
- Combine with conditional visibility on parent rows to show/hide based on whether an image exists
- Use the Sizing design options for fixed dimensions rather than dynamic fields when dimensions are consistent
What's Next
- Handoff Text Module – Display text content from Flexible Content fields
- Handoff Repeater Module – Loop through repeater sub-fields
- Creating Handoff Layouts – Learn how to build Divi Handoff Layouts