Skip to content

Image Box

A grid or slider of images, each with an optional badge plus title / description / link shown as an overlay or a caption, and an optional click action (open a link or zoom in a lightbox). Best for: image galleries, portfolios, feature / service tiles, lookbooks, photo carousels.

Skeleton layout of the Image Box module
Structure at a glance

📷 Hero image

Target file: assets/img/image-box/hero.webp

A three-across grid of square gallery images on a Light background, evenly spaced with rounded corners. Show a small corner badge on at least one tile and a magnifier zoom icon affordance to signal the lightbox. Captured at desktop width.

At a glance

Gallery Grid or slider Lightbox

  • What it does: renders a repeater of images as a responsive grid or a Splide slider. Each image can carry a corner badge and a content block (title / description / link) shown as an overlay on the image or a caption below it. On click, an image can do nothing, follow a link, or open in a lightbox popup.
  • Best used for: a portfolio or lookbook grid, a photo carousel, clickable tiles, or an overlay-on-hover gallery with badges.
  • Not the right fit if: each item needs a full text block and button (use Content Card), or you want text beside one image (use Content and Media).
  • 🔗 Live demo: (add demo link)

Add it to your page

  1. In the HubSpot page editor, click Add and search for Image Box.
  2. Drag it onto your page.
  3. Open Click to update content and choose the View (grid or slider) and the click behaviour (What do you prefer on image click?).
  4. Decide Card style (on = overlay, off = caption below).
  5. Add images in the Images repeater, with badge, title, description, and link per item.
  6. Use the Style tab to set image sizing, badge look, overlay tint, and slider chrome.

Design recipes

Each recipe is a look plus the exact fields to reproduce it.

A clean grid where each image zooms in a popup.

📷 Result

Target file: recipe-lightbox-gallery.webp

A clean grid of square images with a magnifier zoom icon on each tile and no captions. Capture the grid at desktop width so the even columns and zoom affordance are visible.

Field Set to
Content › View grid
Content › What do you prefer on image click? zoom_image_in_popup
Content › Card style off
Image › Ratio of image aspect-1by1

Images with a title and description below, wrapped in cards.

📷 Result

Target file: recipe-caption-cards.webp

Images each wrapped in a card with a title and description in the caption area below, and a soft shadow around each card. Capture the grid at desktop width.

Field Set to
Content › Card style off (caption mode)
Card › Simple card › Make a card on
Card › Simple card › Card shadow regular-shadow

Text reveals only when a tile is hovered.

📷 Result

Target file: recipe-overlay-on-hover.webp

A gallery tile mid-hover, with the title and description revealed over the image under a dark overlay tint while the neighbouring tiles stay plain. Capture at desktop width so the hover reveal is clear.

Field Set to
Content › Card style on
Card › Overlay card › Overlay reveal hover
Card › Overlay card › Overlay Default

A continuous loop with faded edges.

📷 Result

Target file: recipe-auto-scroll-marquee.webp

A single row of images scrolling continuously, with the left and right edges softly faded by the mask. Capture at desktop width so the faded corners and the marquee row are visible.

Field Set to
Content › View slider
Slider › Advanced › Slider functionality auto_scroll (Type = loop)
Slider › Add mask at both corners on

"I want to..." quick reference

Goal Setting
Carousel instead of grid Content › View = slider
Click image to enlarge Content › What do you prefer on image click? = zoom_image_in_popup
Make each image a link Content › What do you prefer on image click? = attach_link
Content on top of the image Content › Card style = on
Content below the image Content › Card style = off (caption mode)
Reveal text only on hover Card › Overlay card › Overlay reveal = hover
Wrap captioned images in cards Card › Simple card › Make a card (grid + caption mode)
Add a corner label Content › Show badge + per item Badge label
Hide the magnifier icon Content › Show zoom icon affordance = off
Square / portrait images Image › Ratio of image (aspect-1by1 / 9by16 etc.)
Fixed pixel-height images Image › Ratio = custom_height + Height [desktop / tablet / mobile]
Image zooms on hover Image › Zoom image on hover + Zoom scale on hover
Continuous auto-scroll Slider › Advanced › Slider functionality = auto_scroll (Type = loop)
Fade slider edges Slider › Add mask at both corners + Mask fade distance
Peek next / prev slides Slider › Advanced › Show all slides in viewport

Field reference

The editor has a Content tab and a Style tab, grouped exactly as they appear in HubSpot. (262 fields total - expand each group as needed.)

Content tab

Click to update content
Field Type Default
View choice (grid / slider) grid
What do you prefer on image click? choice (no_action / attach_link / zoom_image_in_popup) zoom_image_in_popup
Show zoom icon affordance boolean on
Show badge / Show title / Show description boolean on

Images (repeater, per item): Image, Badge label, Title, Description, and the link trio Add link + Link + Link title. The link trio follows What do you prefer on image click?: shown for Attach link and No action, hidden for Zoom image in popup. Add link itself only appears in No action, where it decides whether the link draws.

Drag to section name

Section name: sets this section's ID for scroll-to-section links.

Style tab

Color scheme
Field Options Default
Color scheme light / dark light

Drives the section's surface and text tokens. Set the background Type to none (shown as "Default (scheme)") to let the scheme supply the background colour.

Section background settings

Color / gradient / image / video (overlay + position), blur, parallax, and dual radial glows (color, position, size, opacity).

Section divider settings

Divider type: none / shape / border / shadow, with border, shadow, and 25-shape options (flip / invert, color / gradient, responsive heights).

Section spacing settings
Field Options Default
Top top-y-0 to top-4xl top-xl
Bottom bottom-y-0 to bottom-4xl bottom-xl
Left left-x-0 to left-xl left-m
Right right-x-0 to right-xl right-m

Top and Bottom also accept custom, which reveals Custom top / Custom bottom number fields for desktop, tablet, and mobile (defaults 80 / 60 / 40).

Layout settings
  • Columns: images per row for large / medium / small screens (default 3 / 3 / 1).
  • Slide move and Gap between column: per-breakpoint slides-per-move and gap.
  • Section wrapper container and Inner content container: width + alignment.
Card (grid + caption mode)
  • Alignment: content alignment left / right / center.
  • Simple card: Make a card, background (color / gradient / glass blur), border, responsive padding, shadow, round corner.
  • Overlay card: overlay reveal (always / hover), overlay style, height (hug content / full height), content padding, shadow.
Slider settings
  • Slider navigation: none / dots / arrows / both (default dots).
  • Slider arrows: custom icons, background, icon color, border, round corner, spacing, size, inside vs outside.
  • Slider dots: width / height, round corner, separate simple and active states.
  • Advanced settings: Type (loop / slide), functionality (simple / autoplay / auto_scroll), speed, direction, peek slides.
  • Edge mask: fade the slider edges with an adjustable fade distance.
Preset Settings
  • Image: aspect ratio (9 presets) or custom height per breakpoint, focal point, round corner, hover zoom + scale, caption gap.
  • Badge: position (top-left / top-right), background, text color, padding, round corner, border, font size, bold, transform.
  • Zoom icon: position, background, blur, border, size, hover scale (shown in popup mode).
  • Title: heading tag or custom size (desktop / tablet / mobile), color incl. gradient, transform, spacing.
  • Description: typo style, color, spacing.
  • Link: color, font family, bold, optional icon, icon gap, underline + offset, spacing.
Developer use only

Add custom css here: per-module CSS injection field.

Tips & gotchas

Link fields showing in No action

Under What do you prefer on image click?, the Link and Link title fields stay visible in No action even when that image's Add link is unticked. They draw nothing until you tick it.

That is a HubSpot limit, not a theme choice: field visibility takes one list of conditions joined by a single and or or, with no way to group them, so "Attach link, or No action with the box ticked" cannot be written exactly. The theme uses the closest rule that is never wrong on the page and keeps the exact rule in the rendering. See Why a field sometimes does nothing.

Round corner missing after turning Card UI off?

Card style and Spacing applied on only appear while Card UI is checked, and HubSpot keeps their last values when they are hidden. So if you set Card style to Overlay (or spacing to Content only) and then switch Card UI off, those stored values still apply, and Round corner and Shadow stays hidden with no card left to set it on.

To get it back: turn Card UI back on, set Card style to Simple and Spacing applied on to Whole card, then switch Card UI off again.

This is a HubSpot limitation, not a theme bug: a field can only be shown or hidden by a flat list of conditions, and this case needs a nested one.

Overlay vs caption is one toggle

Card style decides everything: on places the title / description / link as an overlay on the image; off places them as a caption below. Each mode has its own toggles and styling group.

Auto-scroll wants clean edges

For a smooth auto_scroll marquee, set Type of slider to loop and remove pagination dots. Add the edge mask so slides fade in and out at the corners instead of cutting off sharply.

Zoom icon only shows in popup mode

The magnifier affordance (Show zoom icon affordance) appears when image click is set to zoom_image_in_popup. It does nothing in attach-link or no-action modes.

Frequently asked questions

Can the grid switch to a slider only on mobile?

No. View is one setting for the whole module (grid or slider), not a per-breakpoint field, so it applies at every screen size. Pick whichever view fits your smallest breakpoint.

Why is there no Link field on my images?

What do you prefer on image click? defaults to zoom_image_in_popup, which hides the Link and Link title fields entirely. Switch it to Attach link (or No action) to reveal them.

Can one image have a bigger badge than the others?

No, badge styling (size, colour, padding, border, position) is one shared style set on the Style tab. Only the Badge label text, and whether that item shows a badge at all, is set per image in the repeater.

Why doesn't Overlay card settings do anything?

That group is always visible in the editor, but it only takes effect when Card UI is on and Card style is set to Overlay. With Card style on Simple (caption mode), the Overlay card group is set but unused.

If I turn off Show title, does it just hide titles on images that don't have one?

No. Show title, Show description, and Show badge are global switches under Content. Turning one off hides that element on every image at once, even items that have text entered for it.

Does the Columns setting still matter if I switch to a slider?

Yes. Layout settings › Columns sets both the grid's images-per-row and the slider's slides-per-view, so the same desktop / tablet / mobile counts carry over when you switch View.