Foobox - WordPress Plugin

Guide to Setting Up Foobox and Testing Your WordPress Site Lightbox

Foobox is not meant to replace the WordPress gallery or media library. Its job is to make already published images, galleries, videos, and individual HTML blocks easier to view in a modal window. In this guide, we will walk through the full process from installation to verification: which images the plugin picks up automatically, where you need to manually specify a class or a media file link, which settings should be enabled with caution, and what to do if a different lightbox opens instead of Foobox.

This guide is written for site owners, editors, webmasters, and developers who want to clean up image viewing quickly without relying on random settings. We will look separately at WordPress galleries, single images, FooGallery integration, video, captions, script loading optimization, conflict troubleshooting, and safe CSS tweaks for the visual design.

Foobox works best on pages that already contain visual content: portfolios, photo galleries, project showcases, tutorials with screenshots, product images, short video previews, or forms that are easier to display on top of the page. If your site has very little clickable media, the plugin's impact will be modest, so we will start not with the install button but with the underlying mechanics.

How Foobox Hooks Into a Page and Why the Link Matters More Than the Image

The core rule behind Foobox is simple: the plugin does not open the thumbnail itself, but the link that points to a full-size image, video, hidden HTML block, or other supported content. That is why the common situation of "the image is there, but the lightbox does not open" almost always starts with checking the link. If an image is inserted into a WordPress block but is not linked to the media file, Foobox has no clear target to open.

For standard WordPress images and galleries, the safest baseline setup is this: the thumbnail stays on the page, and the click leads to the image file. After activation, the plugin scans the selected areas of the page and picks up those links. The developer makes a point of emphasizing in the documentation that Foobox is not a gallery plugin: it does not create albums, manage thumbnails, or replace the media storage system. Its job is to display already linked visual content in a convenient modal window.

This difference matters for your site structure. If you need a grid, filters, sorting, albums, and collection management, you need a separate gallery plugin or the standard gallery block. Foobox attaches to the result and improves the viewing experience. It works especially naturally with FooGallery, but it is not limited to that plugin: it supports regular WordPress images, galleries, some third-party galleries, and manual links with the appropriate class.

The second important layer is the attachment scope. In the settings, you can tie Foobox to WordPress galleries, images with captions, attachment images, and other link types. For individual blocks, you can use the CSS class field or add the foobox class directly to the link. This approach is useful on complex pages: instead of attaching globally to every image, you can open in the lightbox only the elements that are actually meant to work as media previews.

Check before configuring: open a page with an image, click the image without Foobox, and make sure the browser can open the full-size file. If the click leads to an attachment page, an empty anchor, or nowhere at all, fix the link in the editor first.

When Foobox Is a Good Fit for a Site and When Another Option Makes More Sense

Foobox works well for sites that need a clean media viewer without rebuilding the content structure. It is especially useful for photographers, portfolios, blogs with tutorials, small catalogs, event sites, educational pages, and stores where visitors need to inspect an image without leaving the page. The plugin gives you a modal window, gallery navigation, captions, screen adaptation, and in the paid version additional use cases such as social buttons, video, iframe, HTML content, fullscreen mode, and analytics.

If your content is already organized in standard WordPress galleries, getting started is usually quick. Install it, activate it, make sure the galleries link to the Media File, and check the appearance. On an older site where images were inserted for years without links, it will take more attention. In the recent WordPress.org changelog for Foobox, the Auto Link Existing Images setting was added to help automatically wrap older attachments with a media file link. That is useful, but it is best to test that feature first on a copy of the page or on a few representative posts, because older content may have been built with different editors and themes.

The plugin may be unnecessary if the site uses only a couple of standalone images with no need for enlargement, if the theme already provides a solid lightbox that cannot be disabled, or if the task is broader: a full media gallery with filters, access protection, file sales, and complex albums. In those cases, Foobox may be part of the solution, but not the only tool.

It is also worth considering built-in WordPress and theme capabilities. Modern gallery blocks have basic image enlargement options, and many commercial themes already ship with their own viewing script. Foobox includes a setting to disable some popular third-party lightbox scripts, but the developer is upfront about the limitation: if the lightbox is deeply built into the theme, that setting may not fully remove the conflict. In that case, it is better to look for a native theme switch or ask the theme developer to add one.

What to Check Before Installation and First Activation

Before installing Foobox, it helps to open one typical gallery page and one page with a single image. Check how clicks work right now: does the click open the file, an attachment page, the theme lightbox, or nothing at all? This quick review saves time because after activating Foobox, you will not be seeing plugin magic. You will be seeing the result of the page's current HTML structure.

For WordPress, there are four things worth checking. First, images in the block editor or classic editor need to be linked to the media file if you want automatic triggering. Second, the theme needs to output content correctly and not break standard WordPress hooks. Third, caching, JavaScript optimization, and deferred script loading should not shift initialization in a way that makes the Foobox code run before its main file. Fourth, a second lightbox should not be opening on the same page, or visitors may see double overlays or odd dimming behavior.

If you are using a caching or optimization plugin, note its settings in advance: JS combining, deferred loading, footer placement, and delayed execution until interaction. Foobox has already had changelog fixes related to conflicts and script optimization, so these issues should be diagnosed calmly: first disable aggressive optimization on a test page, then turn settings back on one by one.

Another preparation step is choosing test pages. Do not test only in the admin panel or on a single new post. Use:

• A page with the standard Gallery block.
• A post with a single image and a caption.
• An older post where images may have been inserted without links.
• A page where the theme or another plugin already shows a lightbox.
• A mobile screen or browser emulator to check sizing, closing, and navigation.

This will show you right away where Foobox works out of the box and where it needs precise setup. Do not try to enable every mode at once: first get a standard gallery working reliably, then add single links, CSS classes, social buttons, video, or selective asset loading.

Installation and the First Check After Activation

Installing Foobox follows the standard WordPress plugin workflow: either through the plugin directory or by uploading a ZIP file if you already have the archive. After activation, there is no need to start changing dozens of settings. First, open the public side of the site and test the basic scenario: clicking an image in a gallery should open a modal window, dim the page behind it, and return the visitor to the same spot when closed.

In the admin panel, go to the Foobox settings and find the tab with general options. The exact tab and item names may vary a little between interface versions, but the logic stays the same: first you choose which images and links the plugin attaches to, then you configure the appearance, window behavior, captions, extra features, and JS/CSS. For the exact English interface labels, look for Settings, General, Look & Feel, Functions, Advanced, JS & CSS, and Save Changes.

The initial check should be short and repeatable:

1. Open a gallery page in Incognito mode or after clearing the cache.
2. Click the first thumbnail and confirm that the Foobox modal opens.
3. Move to the next image with the arrow or keyboard key, if navigation is available for that gallery.
4. Close the window and make sure the page does not jump to an unexpected position.
5. Repeat the test at a mobile width and confirm that the image stays within the screen.

If the basic test fails, do not move on to colors and animation. First confirm that clicking the image leads to the file itself. In the block editor, that is usually controlled by the image or gallery link setting. For older content, the newer Auto Link Existing Images setting may help, but it should be used only after testing on a small sample of posts.

Configuring Attachment Areas: Galleries, Single Images, and CSS Classes

The most important Foobox settings section answers one question: which links should the plugin pick up? For a typical site, it makes sense to start with WordPress galleries and images linked to the media file. If you enable an overly broad mode such as all image links on a large site, you may accidentally catch utility images, icons, cards, or links that are supposed to open separate pages.

WordPress Galleries and the Media File Link

For a standard gallery, the main control is not only in Foobox but also in the WordPress editor. In the Gallery block, make sure the items link to the Media File. If the gallery points to attachment pages, the user will leave for separate image pages, and Foobox will not be able to open the full-size file correctly in a modal window. Lightbox setup starts with the right link in the content, not with the frame color.

After changing the link, update the page and check the public side. If the site uses page caching, clear the cache or open the URL with a test parameter. If the gallery was created by a third-party plugin, check that plugin's settings: sometimes the lightbox is chosen not in Foobox, but in the gallery's own options.

Single Images and the Specific CSS Classes Field

Single images usually require more care. If you want Foobox to work only inside the main content area, specify the CSS selector for that region, such as .entry-content, .content, or your theme's selector. The developer documentation recommends exactly this approach: the plugin needs to know where to look for elements to attach to, especially if images are located not only inside a gallery but also in a sidebar or custom block.

On a complex site, it is better not to add too many areas at once. Start with the main post container, check the result, then add the sidebar or another block only if it is truly needed. A mistake in the selector will cause Foobox either to miss links or to pick up extra elements.

Manual Triggering with the foobox Class

If you need a targeted link, you can add the foobox class to the link. This works well for an "Open Image" button, a video link in a Pro scenario, or a hidden HTML block. A standard image example looks like this:

<a class="foobox" href="https://example.com/uploads/photo-large.jpg" data-caption-title="Project before the update" data-caption-desc="Detailed view of the result">Open Image</a>

This snippet does not require editing theme files: you can use it in an HTML block if the editor allows that markup. After inserting it, test the link on the public side. If the window does not open, make sure the Foobox scripts are loading on the page and that your optimizer has not delayed their execution.

Appearance, Captions, and Window Behavior

Once the basic trigger is working, you can move on to appearance. Foobox includes settings that affect the window theme, color scheme, icons, loader, captions, counter, and window behavior. There is no need to change everything. A well-tuned lightbox should support the content, not compete with it.

Size and Screen Adaptation

One of Foobox's strengths is fitting images into the available space. But a setting like Fit to Screen needs to be understood correctly. If the original image is small, forcing it to stretch can make it look blurry. On a photography site, it is better to upload images that are large enough and not rely on enlarging low-quality files. For screenshot-based tutorials, the text inside the image needs to remain readable while the window still stays within screen bounds.

Captions and Data Sources

Captions can be pulled from different places: caption, title, alt text, or data attributes. The Foobox documentation describes three paths: via settings, via data-caption-title and data-caption-desc, or via custom JavaScript for advanced cases. For most sites, the first two are enough. If your editors already fill out captions carefully in the media library or image block, do not duplicate that text manually. If you need a unique caption for a single link only, use data attributes.

For SEO, lightbox captions are not a replacement for proper on-page text. Search engines care more about the surrounding content, the image alt text, and the page structure. So Foobox should be used as a UX layer, not as a way to hide important descriptions inside a modal window. Critical text should remain in the page HTML, while the lightbox caption can help the visitor stay oriented.

Navigation, Closing, and Hiding Page Scrollbars

Settings such as Hide Page Scrollbars, Close on Overlay Click, Hide Navigation Buttons, and the image counter all affect usability. In a photo gallery, the counter is useful because the visitor can see how many images are left. For single screenshots, it may be unnecessary. Hiding background scrollbars makes the modal feel calmer, but it can also cause a slight page width shift when the scrollbar disappears. If the layout "jumps" after the window opens, try turning that option off and compare the result.

How to Use Foobox in a Real-World Scenario: A Portfolio Gallery with Result Verification

For the practical example, let us use a studio, craft business, photographer, or agency site. The goal is to show a grid of work on a page and open a larger image in a lightbox when clicked, without sending the user to a separate attachment page. This is a good illustration of how Foobox works: the content is created in WordPress, the link points to the media file, and the plugin opens the viewer and provides navigation.

Goal and Preparation

We need a "Projects" page with a gallery of several images. Before you start, upload images that are large enough and fill in alt text and captions where they help explain the work. Do not insert huge uncompressed files just for the lightbox: Foobox may display the image nicely, but load speed still depends on media size and site optimization.

Setup Steps

1. Create or open the page where the project gallery will appear.
2. Add a Gallery block and choose several images from the media library.
3. In the gallery settings, set the images to link to the Media File if that option is available in your editor.
4. Save the page and open it on the public side of the site.
5. In the Foobox settings, make sure attachment to WordPress galleries is enabled.
6. Click the first thumbnail and check the modal window, navigation, caption, and closing behavior.
7. Check the same page at a mobile width: the image should fit on screen and the close button should remain accessible.

Check After Saving the Page

After updating the page, open it as a regular visitor rather than from the editor preview. If the site uses caching, clear the page cache and click both the first and last thumbnail again. This verifies not only the new markup, but also that the public version of the page received fresh links to the media files.

Expected Result

The visitor sees a standard image grid. On click, a larger version opens in a modal window, the page remains behind it, the visitor can move to neighboring images, and the window can be closed without losing position on the page. If captions are configured, they help explain what is shown. If the counter is enabled, the user can see their place in the set.

A Detail That Often Gets in the Way

The most common issue in this example is that the gallery does not link to the Media File. The page looks fine visually, the thumbnails are in place, but Foobox has no valid target. The second common cause is that another lightbox is already built into the theme or gallery plugin. If the click opens the wrong interface or two windows at once, go back to the troubleshooting section and start by disabling the built-in lightbox in the theme or in the specific gallery settings.

Practical Ways to Use Foobox Across Different Page Types

Foobox should not be enabled just for the effect itself. It works best when the lightbox helps someone inspect a detail faster, compare images, or complete an action without leaving the page. Below are several use cases based on confirmed plugin capabilities and standard WordPress practice.

Portfolios and Case Studies

In a portfolio, Foobox works well as a second layer after the project grid. The page keeps a compact selection, while the details open in a large viewer. Captions matter especially here: they can provide a short explanation of the image, but the full project description is better left in the article or case study itself. Make sure the navigation follows the right order and that thumbnails do not point to attachment pages.

Tutorials with Screenshots

In instructional articles, thumbnails often save space, but users still need to inspect the interface. Foobox lets them open a larger screenshot. In this kind of use case, readability matters more than animation: do not stretch small screenshots, do not hide key text only inside the image, and add captions when the step is not obvious.

Video and Hidden Content

In Pro scenarios, Foobox can open YouTube, Vimeo, iframe, inline HTML, and forms. That is useful for a short video, a contact form, or a demo block. But you need to be more careful here: an oversized iframe on mobile, heavy forms, or autoplay video can make the experience worse. Start with one element, set reasonable dimensions, and test how closing works on mobile.

Older Posts with Single Images

If your site has been publishing image-heavy content for a long time, the newer Auto Link Existing Images and Default Image Link settings can reduce manual work. But do not turn them on blindly across the whole site. Check a few older posts: on some pages the image should open in a lightbox, while on others the image click may have been intended to lead to another page. If those cases are mixed, automatic behavior may be too broad.

Performance, Caching, and JS/CSS Loading

Foobox adds JavaScript and CSS to the site, so performance tuning should be intentional. The official documentation explains that because of how WordPress content works, the plugin may load its assets on all pages by default: it is not always possible to know in advance where an image, video, or shortcode will appear. That is normal for a site with a lot of visual content. For a small site where the lightbox is needed on only one or two pages, exclusions are worth using.

Under Advanced settings, there is an Exclude FooBox Assets mode. If you enable it globally, the assets stop loading everywhere, and you can then enable them on specific pages through the FooBox Javascript & CSS metabox. This approach requires discipline: the editor needs to remember that assets must be enabled on any page that uses the lightbox. But it reduces unnecessary loading where Foobox is not needed.

Caching and JS optimization can produce the opposite effect. If combining scripts or deferring them changes execution order, Foobox may fail to initialize. The WordPress.org FAQ directly describes the FooBox is not defined symptom, which happens when initialization runs before the main script. In those cases, check that the plugin is updated, exclude the Foobox inline script from delay, and temporarily disable aggressive optimization for the test page.

A safe performance testing order looks like this:

1. First get Foobox working correctly without JS optimization.
2. Enable page caching and check the result in Incognito mode.
3. Turn on minification, combining, and JS delay one setting at a time.
4. After each change, test gallery opening, window closing, and the browser console.
5. If the error returns, roll back the last setting and add an exclusion for Foobox scripts.

Good performance tuning should not break the core feature. If the lightbox stops opening just to save a few kilobytes, it is better to use more selective asset loading than aggressive delay on every script.

Safe Visual Tweaks with CSS

The Foobox developer publishes a CSS cheat sheet and recommends adding styles through the Custom CSS field on the JS & CSS tab or through your theme styles, rather than editing plugin files. That is the right approach: a plugin update should not wipe out your small customization, and rolling it back should take a minute.

Below is an example of a subtle background and caption tweak for a light design. Use it only after you have chosen a compatible light scheme, and test it on several images. The code does not change how Foobox works, only the appearance of the modal window.

/* Foobox: subtle background and more readable caption */
.fbx-modal {
  background: rgba(18, 24, 32, 0.78) !important;
}

.fbx-light .fbx-caption {
  font-size: 15px;
  line-height: 1.45;
  color: #1f2933;
}

.fbx-light .fbx-caption-title {
  font-weight: 700;
}

Where to put it: in Foobox Custom CSS settings or in the child theme CSS. How to test it: open an image with a short caption, then an image with a long description, then a gallery at a mobile width. If the caption becomes too large or covers the image, remove the snippet and go back to the default settings. Do not edit the plugin's own CSS files: an update will overwrite the changes and make troubleshooting harder.

Rolling it back is simple: remove the added CSS, save the settings, and clear the cache. If the change was added to a child theme, comment out the block and test the page again. For more complex changes, such as a different button structure or custom events, it is better to review the Foobox jQuery event documentation first and avoid dropping in random forum snippets.

How to Verify That the Result Works for Visitors

Result verification should imitate a real visitor, not an administrator with the toolbar open. Administrators often see uncompressed assets, bypass the cache, or load the page under different conditions. Open the public page in a private window, under another user role, or with the admin bar disabled.

Quick Pre-Publish Checklist

• Clicking a thumbnail opens the modal window instead of an attachment page.
• The close button, Escape key, and background click behave as expected for the chosen settings.
• The caption is readable and does not cover an important part of the image.
• Navigation between images works only within the intended gallery.
• At mobile width, the image fits on screen and the controls remain accessible.
• The browser console shows no Foobox-related errors or JavaScript load-order issues.
• After enabling caching, the result matches the no-cache test.

If the site has analytics, do not jump to conclusions about higher engagement just because a lightbox was installed. The Pro version includes analytics options for tracking opens, events, and social actions, but those need to be configured separately and interpreted with care. For a typical site, it is enough to verify the behavioral result first: the visitor opens an image, can move to the next one, closes the window, and continues reading the page.

When Foobox Is the Right Choice for Your Site

Foobox is worth using if your site already has images, galleries, or media links that need a clean viewing experience without sending users to a separate page. It is especially convenient when editors work with standard WordPress galleries, when you want to improve the viewing experience for a portfolio or tutorial quickly, or when the site already uses FooGallery and wants a unified lightbox layer.

Before you download the ZIP archive, check three things: your images should link to the media file, the theme's built-in lightbox should be disabled or at least not conflict, and caching plus JavaScript optimization should not break the load order. After installation, configure only the attachment areas you actually need, test the public page, and only then move on to colors, captions, Pro scenarios, and CSS refinements.

If you need a full system for albums, filters, and collection management, Foobox works better alongside a gallery plugin or should be replaced with another tool. But if the goal is to make images, galleries, video, or HTML content easier and cleaner to view, Foobox handles that without forcing a heavy site rebuild. The most reliable readiness test is simple: the visitor clicks a thumbnail, sees the larger content, understands the caption, closes the window, and continues working with the page.