Overview
The Image Button element is the clickable counterpart to the Image element. It displays a visual — a photo, illustration, or graphic — that users can tap or click to make a selection and advance through the experience.
Note: This article covers the Image Button element. For non-interactive image display, see the Image Element article.
Supported File Types & Specs
Property | Recommendation |
Image formats |
|
Image file size | ~300KB recommended, 2MB max |
Video file size | 20MB max |
Min resolution | 600 × 600px |
Adding an Image Button Element
Open your experience in the Builder and navigate to the screen you want to edit.
Click "Add Element" to open the element panel.
Select Image Button from the element list.
Upload your image from the Media Library or paste an external URL.
Image Buttons are typically placed inside a Container element to control their layout and column arrangement.
Resizing & Repositioning
Width and height are set in the Sizing section of the control panel. The width unit can be toggled between % and px by clicking the unit label next to the width input.
To reposition, use the up arrow or down arrow buttons next to the preview window.
Free-form positioning is another way to position elements — see the Free-Form Positioning article for details.
Control Panel Options
When an Image Button element is selected, the left control panel displays the following options in order.
Option | What it does |
Image |
|
Media | Opens the Asset Picker to upload a new image or select from your media library. |
Image Transparency | Sets the opacity of the image (0–100%). Lower values make the image more transparent. |
Size Mode | Controls how the image fills the button: Show All (full image, no cropping, may show background), Fit the Space (fills bounds, crops as needed), Original (100% of actual pixel size). |
Positioning (9-point grid) | When Fit the Space is selected, controls which part of the image stays visible. Top Left, Top Center, Top Right, Middle Left, Center, Middle Right, Bottom Left, Bottom Center, Bottom Right. Has no effect on Show All or Original. |
Border & Shape |
|
Corner Radius | Rounds the corners of the button — from subtle softening to a fully circular shape. |
Border Width | Sets the border thickness in pixels. Set to 0 for no border. |
Border Color | Sets the border color. Only visible when Border Width is greater than 0. |
Shadow | Applies a default drop shadow. |
Text |
|
Text Position | Controls where the text label appears: Text on Bottom, Text on Center, Text on Top, Text as Overlay (Centered), or Text Underneath (below the image). |
Overlay Color | Sets the background color of the text area for inside text positions. |
Color | Sets the text label color. |
Hide Text | When enabled, hides the text label from users. A Label field appears — this is required for reporting even when text is hidden. |
Font | Sets the typeface for the text label. |
Size | Sets the font size. |
Line Height | Controls vertical spacing between lines of text. |
Boldness | Sets the font weight. |
Italic | Toggles italic styling. |
Text Alignment | Aligns label text Left, Center, Right, or Justified. |
Layout |
|
Button Alignment | Controls horizontal placement within the available space — Left, Center, or Right. |
Spacing | Controls the margin around the element — the space between it and neighboring elements on the screen. Individual values can be set for Top, Bottom, Left, and Right. |
Sizing | Sets explicit width and height. Width unit can be toggled between % and px. |
Advanced Settings |
|
Animation | Applies an entrance animation when the screen loads. |
Animation Delay | Sets a delay in seconds before the entrance animation plays. |
State | Switches the control panel between Default, Hover, and Active states. Each state can have its own independent styling — different image, border, text color, shadow, and more — allowing the button to visually respond when a user hovers over or clicks it. |
Note on Hover state: The Hover state only applies on desktop. To edit it, switch to Desktop view using the device switcher at the top of the editor. Hover is not available on mobile since touch devices do not have a hover interaction.
Style Independently (Desktop vs. Mobile)
Enable Style Independently (SI) via the SI icon on the element tag to apply different styling per device. Use the "Apply mobile design" option in the element's context menu to sync one view to the other.
Click Action & Response Mapping
The click action determines what happens when a user selects the button — navigate to the next screen, navigate to a specific screen, or open an external URL. Configure this in the control panel or via the Builder Map connections.
Buttons can also be mapped to a profile attribute in Builder Map → Map Attributes to capture responses as data.
Using Image Buttons in Containers
The Columns setting on the parent Container controls how many Image Buttons appear per row. When Fluid Content is enabled on the Container, Image Buttons scale dynamically — note that Columns is not available in this mode. For mixed-row layouts, use two separate Container elements.
Accessibility Considerations
Ensure sufficient color contrast between the text label and the overlay color or image underneath (minimum 4.5:1 ratio recommended).
Keep button sizes large enough to be easily tappable on mobile devices.
Quick Reference
Option | Where to Configure |
Resize (width & height) | Control panel → Sizing |
Width unit (% or px) | Click the unit label next to the width input |
Reposition | Up / Down arrows next to preview window |
Free-form placement | |
Change image | Control panel → Media |
Image transparency | Control panel → Image Transparency |
Size mode | Control panel → Size Mode |
Image crop anchor | Control panel → Positioning (9-point grid) |
Corner radius | Control panel → Corner Radius |
Border | Control panel → Border Width + Border Color |
Shadow | Control panel → Shadow |
Button alignment | Control panel → Left / Center / Right icons |
Text position | Control panel → Text Position icons |
Overlay color | Control panel → Overlay Color |
Text color | Control panel → Color |
Hide text (with label) | Control panel → Hide Text toggle + Label field |
Font / Size / Style | Control panel → Font, Size, Line Height, Boldness, Italic |
Text alignment | Control panel → Left / Center / Right / Justified icons |
Spacing (margin) | Control panel → Spacing |
Sizing (width & height) | Control panel → Sizing |
Click action | Control panel or Builder Map connections |
Attribute mapping | Builder Map → Map Attributes |
Animation | Control panel → Choose animation style |
Animation delay | Control panel → Animation Delay |
State (Default / Hover / Active) | Control panel → State selector |
Hover state editing | Switch to Desktop view first |
Desktop vs. Mobile styling | Style Independently (SI) toggle |
Column layout | Parent Container element settings |