FooGallery v3.0 — Custom CSS Migration Guide

Purpose: help you update older CSS (from v2.3–v2.5 era) so it works with the new v3 HTML/CSS structure and design system.

What changed in v3?

FooGallery 3.0 shipped a major UI refactor and a modernised design system. As part of this work:

Several class names and DOM structures changed (notably around captions and overlays).
Gallery presets exist in FooGallery and are treated as locked design combinations. Many presets set their own typography, spacing and colours. Customising them comes with a higher risk of layout issues and should only be done if you’re comfortable with CSS.
There’s now a detection banner in WP‑Admin that flags custom CSS that most likely needs updating (you’ll see it on FooGallery → Galleries and FooGallery → Settings → Custom JS & CSS).

If you see “FooGallery – Custom CSS Update Required”, it means we detected custom CSS targeting captions. We can’t tell if your styles will break—only that you have caption customisations to review. Check your galleries after the update and adjust your CSS only if needed. The notice is a one‑time heads‑up on install/update and can be dismissed; it isn’t re‑run on every save.

Where is my CSS stored?

Check each of these in order until you find your rules:

Per‑gallery Custom CSS — on the gallery edit screen (Custom CSS meta box). Use when you want styles for a single gallery only.
Global CSS in FooGallery — FooGallery → Settings → Custom JS & CSS → Custom Stylesheet. Use when you want styles to affect every gallery.
Theme/Child theme — style.css or a theme options panel.
Customizer — Appearance → Customise → Additional CSS.

If you manage dozens or hundreds of galleries, prefer global CSS and class‑based selectors so you don’t duplicate rules in dozens of places.

Scope: global vs one gallery

You have two safe ways to scope selectors in v3:

Global (all galleries): start with the base class .foogallery…

/* Applies to every FooGallery on the site */
.foogallery .fg-caption { /* … */ }
Code language: CSS (css)

Single gallery: target the gallery ID shown on the editor screen/shortcode, e.g. #foogallery-gallery-1493

/* Applies only to gallery ID 1493 */
#foogallery-gallery-1493 .fg-caption { /* … */ }Code language: CSS (css)

Rule of thumb: if you’re pasting CSS into the per‑gallery Custom CSS box, use the ID selector so nothing else is affected. If you’re pasting into global CSS (Customizer, theme, or FooGallery → Settings), use the .foogallery class.

Presets and why your rule might not apply

Many v3 layouts ship as presets with their own typography, spacing and colours. Presets are intentionally designed so they “just work” without custom CSS.

The examples below include :not(.fg-preset) so your global tweaks skip preset galleries by default (safer).
If you purposely want to target presets, change the first part of each selector from:

.foogallery:not(.fg-preset) …Code language: CSS (css)

.foogallery.fg-preset …Code language: CSS (css)

Disclaimer: Presets are intended to be locked designs. Editing them with arbitrary CSS can break layout because each preset uses different baseline values (e.g. margins, padding, backgrounds). Prefer switching a gallery off the preset first, or clone its settings into a custom layout and then style that.

Targeting a specific preset (advanced)

If you must customise a particular preset, target it by name so other presets aren’t affected:

/* Generic form */
.foogallery.fg-preset.fg-<preset-name> { /* prop: value; */ }

/* Example: tweak the caption title in the “goliath” preset */
.foogallery.fg-preset.fg-goliath .fg-caption-title {
  font-family: monospace;
  font-size: 20px;
  color: hotpink;
}Code language: CSS (css)

Replace <preset-name> with the preset’s class (e.g. fg-goliath). Validate thoroughly after changes.

Quick fixes for common breakages

1) “My caption text colour stopped working” (classic v2 rule)

Old (v2.x):

.foogallery .fg-caption {
  background-color: #f00e43;
  color: #ffffff;
  padding: 5px;
  font-weight: bold;
}Code language: CSS (css)

Why it broke: in v3, the caption text is split into *.fg-caption-title* and *.fg-caption-desc*. Colour set on the container may no longer cascade as you expected.

New (v3):

/* Background for the caption container */
.foogallery:not(.fg-preset) .fg-caption {
  background-color: #f00e43;
  padding: 5px; /* optional: keep your spacing */
}

/* Text colour for the caption bits */
.foogallery:not(.fg-preset) .fg-caption-title,
.foogallery:not(.fg-preset) .fg-caption-desc {
  color: #fff;
  font-weight: 700; /* mirrors your old bold */
}Code language: CSS (css)

Target just one gallery: prefix with its ID, e.g. #foogallery-gallery-1493 .fg-caption….

2) “I need to update 200+ galleries”

Don’t paste CSS into each gallery. Put one set of global rules in Appearance → Customise → Additional CSS or FooGallery → Settings → Custom JS & CSS and scope them with .foogallery… (or with .foogallery.fg-preset... if you truly must hit preset layouts). This ensures your fix applies everywhere.

v3 caption selector cheat‑sheet

Use these safe selectors as a starting point when styling standard (non‑preset) galleries:

/* 1) Change typography for standard captions */
/* Title */
.foogallery:not(.fg-preset) .fg-caption-title {
  font-family: monospace;
  font-size: 20px;
  color: hotpink;
}

/* Description */
.foogallery:not(.fg-preset) .fg-caption-desc {
  font-family: monospace;
  font-size: 14px;
  color: hotpink;
}

/* 2) Change padding for caption content */
.foogallery:not(.fg-preset) .fg-caption .fg-caption-inner {
  padding: 30px;
}

/* 3) Change overlay icon (hover/zoom) */
.foogallery:not(.fg-preset) :is(.fg-caption-inner, .fg-image-overlay)::before {
  background-image: url(../assets/img/icons.svg#image-light);
  background-size: 32px 32px;
}

/* 4) Change the caption backdrop colour */
.foogallery:not(.fg-preset) .fg-caption {
  background-color: #00b9ff;
}Code language: CSS (css)

Swap the first selector segment to #foogallery-gallery-123 … to target one gallery. Swap to .foogallery.fg-preset … if you must style a preset (use with care).

Old → new mapping (captions)

What you used to target	v3 target now	Notes
.foogallery .fg-caption { … }	.foogallery .fg-caption { … } and .foogallery .fg-caption-title, .foogallery .fg-caption-desc { … }	Container still exists; text parts now have their own classes.
.foogallery .fg-caption .inner { … } (or similar)	.foogallery .fg-caption .fg-caption-inner { … }	Inner wrapper renamed/standardised.
Global rules without gallery scoping	.foogallery …	Always scope to .foogallery (or a gallery ID) to avoid theming conflicts.

This is not a full DOM map, but it covers the common cases that typically break after upgrading.

Specificity, performance & maintainability tips

Start broad, then add specificity only if needed. Many issues come from over‑specific older rules that no longer match.
Prefer class selectors over deep element chains; they’re more resilient to markup shifts.
Use !important only as a last resort; first try increasing specificity (e.g. add .foogallery…) or remove conflicting rules.
Keep global tokens together (colours, fonts, spacing) so future changes are one‑line edits.
If you run optimisation/minify plugins, purge caches after saving CSS changes.

Migration checklist

Upgrade to v3.0+ and visit FooGallery → Galleries. If you see the Custom CSS Update Required notice, click through to FooGallery → Settings → Custom JS & CSS.
Locate any CSS you previously added (per‑gallery, global, theme, Customizer).
Update caption rules using the v3 selector cheat‑sheet above.
If you rely on presets, decide whether to leave them untouched or purposefully target them with .foogallery.fg-preset… and validate the layout thoroughly.
Test: view a few galleries on the front end, hover images, and open lightboxes. Check multiple devices. Clear caches if needed.
Repeat for any other heavily customised bits (borders, hover states, spacing). Apply the same scoping principles.

Troubleshooting

About the admin banner. The banner appears on install/update if caption CSS is detected. It’s informational and not tied to saving settings. Once dismissed, it shouldn’t show again until a future install/update.
My change doesn’t show. Clear any page/cache/minify plugins and your CDN. Then hard‑refresh the page (Shift‑Reload).
Only one gallery should change, but all changed. You used .foogallery… (global). Switch to the specific gallery ID, e.g. #foogallery-gallery-1493….
A preset layout looks broken after my edits. Revert your CSS or remove the .fg-preset targeting. Consider switching that gallery off the preset before styling.

Need examples tailored to your site?

Send the gallery URL and a small snippet of your current CSS to our support forum. We’ll reply with the v3‑equivalent selectors and suggested rules you can paste in.

Appendix — Worked examples

A. Global white text on red captions (all non‑preset galleries)

.foogallery:not(.fg-preset) .fg-caption { background-color: #f00e43; }
.foogallery:not(.fg-preset) .fg-caption-title,
.foogallery:not(.fg-preset) .fg-caption-desc { color: #fff; }Code language: CSS (css)

B. Single gallery, extra caption padding

#foogallery-gallery-1493 .fg-caption .fg-caption-inner {
  padding: 24px 16px;
}Code language: CSS (css)

C. Target a preset (advanced — validate layout!)

Presets are locked designs. If you must customise one, target the specific preset class so other presets remain unchanged.

/* Generic pattern — replace <preset-name> with the slug, e.g. fg-goliath */
.foogallery.fg-preset.fg-<preset-name> { /* prop: value; */ }

/* Example: tweak the caption title in the “goliath” preset */
.foogallery.fg-preset.fg-goliath .fg-caption-title {
  font-family: monospace;
  font-size: 20px;
  color: hotpink;
}

/* Scope to a single gallery using its ID + preset */
#foogallery-gallery-1493.fg-preset.fg-goliath .fg-caption-desc {
  opacity: .9;
}Code language: CSS (css)

Tips

Avoid broad .foogallery.fg-preset … rules; each preset has different margins/padding/backgrounds.
Prefer cosmetic changes (colours/type). Test layout-affecting properties (margin/padding) carefully across breakpoints.

.foogallery.fg-preset .fg-caption-title { font-size: 18px; }Code language: CSS (css)

Last updated: October 2025 (covers FooGallery 3.0.0+).

FooGallery

FooBox

FooBar

FooConvert

FooGallery Documentation