Optimole Docs

Appearance

Optimole - Settings Reference ​

Optimole is a cloud-based image optimization plugin that automatically compresses, resizes, and delivers your images through a global CDN. You can find the settings page in the WordPress admin under the Optimole top-level menu item, then clicking the Settings tab at the top of the dashboard.

All settings below (except those under General) are disabled when Enable Optimole Image Handling is turned off.

General ​

Enable Optimole Image Handling ​

When enabled, Optimole manages, optimizes, and serves all the images on your website. This is the master switch for the entire plugin. If you disable it, optimization, lazy loading, and every other feature stops working. All other settings tabs become inaccessible while this is off.

Enable Optimole Badge ​

This setting only appears if your Optimole account status is active.

When enabled, a small Optimole badge appears on the front end of your site. Enabling it earns you 20,000 extra free visits per month on the Optimole free plan. If you do not want a visible badge on your site and do not need the extra quota, leave it off.

When enabled, an expandable Badge settings panel appears with two sub-options:

  • Show only Optimole icon toggles whether the badge displays the full Optimole branding or just the icon.
  • Badge Position lets you choose Left or Right to control which side of the page the badge appears on.

Clear Cached Resources ​

This section provides buttons for manually invalidating Optimole's CDN cache. Use it when you have replaced or edited images on your server and the old versions are still showing on the front end. Clearing the cache forces Optimole to re-fetch and re-optimize from your origin.

Clear cached images purges all cached image assets. A Clear cached CSS & JS button also appears here when Serve CSS & JS Through Optimole is enabled under the Compression settings. Note that clearing the cache temporarily re-optimizes all resources, which may briefly affect site performance.

Image Storage ​

Store Your Images in Optimole Cloud ​

This page controls whether your media library images are stored only in Optimole Cloud or on both your server and the cloud. You choose between two options:

  • Optimole Cloud and your website keeps images on both your server and Optimole. This is the default. Images are optimized and served from the CDN but the originals remain in your hosting storage.
  • Optimole Cloud only transfers images off your server and stores them exclusively in Optimole Cloud. New uploads are automatically sent to the cloud. This frees up hosting disk space but means the originals no longer exist on your server.

When you switch to cloud-only storage, a confirmation dialog appears and the plugin begins transferring existing images in the background. You can monitor progress via the progress bar and logs that appear on this page. A Sync images button lets you re-trigger the transfer for any images that were not yet moved. Switching back triggers a rollback that pulls images from the cloud back to your server.

If conflicting plugins are detected (such as other media offloading or cloud storage plugins), a warning appears listing them and asking you to deactivate them before proceeding with a rollback.

If WordPress cron is disabled on your site, an error appears because the background transfer process depends on it.

Offloading images is a Pro feature. Free plan users see a notice explaining this and are prompted to upgrade.

Advanced ​

The Advanced section is a collapsible group in the settings sidebar. It expands to reveal five sub-pages: Watermark, Compression, Resize, Lazyload, and Exclusions.

Watermark ​

Watermark configuration is managed entirely in the external Optimole Dashboard, not within WordPress. This page provides a link to open the Optimole Dashboard watermark settings and a link to the documentation. The capabilities include choosing watermark position and opacity, setting different watermarks per image size, and creating rule-based targeting by filename, page URL, class, and more.

Compression ​

Compression Mode ​

This control lets you pick one of three overall optimization strategies:

  • Speed Optimized prioritizes faster loading by applying balanced lossy compression. It enables automatic format selection, auto quality, network-based optimization, and metadata stripping, while disabling retina quality. Choose this if page speed is your primary concern.
  • Quality Optimized delivers high-quality images with lossless or near-lossless optimization. It enables all the same features as Speed Optimized but also turns on retina quality and disables network-based optimization. Choose this for photography portfolios or sites where visual fidelity matters most.
  • Custom gives you individual control over each compression setting listed below. When you select Custom, all of the following toggles become visible and independently adjustable.

Automatic Best Image Format Selection ​

Only visible when Compression Mode is set to Custom.

When enabled, Optimole automatically selects the most efficient format for each image, trying options like AVIF and WebP to balance quality with file size. The format chosen depends on what the visitor's browser supports. Note that uncached images may take slightly longer on their first load while the optimal format is being generated.

Retina Quality ​

Only visible when Compression Mode is set to Custom.

When enabled, Optimole serves higher-resolution images to devices with Retina or high-DPI screens, producing sharper results. Images under 150 pixels wide always get retina treatment regardless of this setting. Enable this if your audience commonly uses high-resolution devices and you want crisp images. Disable it to reduce bandwidth usage.

Network-based Optimizations ​

Only visible when Compression Mode is set to Custom.

When enabled, Optimole automatically detects slow network connections and reduces image quality on the fly so that images load faster for visitors on low-speed internet. This is useful for audiences on mobile or in regions with unreliable connectivity. Disable it if you want every visitor to receive the same quality regardless of connection speed.

Serve CSS & JS Through Optimole ​

Only visible when Compression Mode is set to Custom.

When enabled, Optimole processes your CSS and JavaScript files, optimizes any images referenced inside them, and delivers the files through its CDN. This can improve loading speed for stylesheets and scripts. Enabling this also makes the Clear cached CSS & JS button appear on the General settings page.

Strip Image Metadata ​

Only visible when Compression Mode is set to Custom.

When enabled, Optimole removes EXIF and IPTC metadata from images, including camera settings, GPS coordinates, and copyright information. This makes image files lighter and improves load times. Disable it only if you need to preserve metadata for attribution or organizational purposes.

Auto Quality Powered by ML (Machine Learning) ​

Only visible when Compression Mode is set to Custom.

When enabled, Optimole's machine learning algorithms automatically predict the optimal compression level for each image, finding the smallest file size with the least perceptible quality loss. When you disable this toggle, a manual quality slider appears.

The quality slider ranges from 50 (low quality, smallest files) to 100 (high quality, largest files), with reference marks at Low (55), Medium (75), and High (90). A sample image comparison (Original vs. Optimized) is shown below the slider so you can visually judge the effect of your chosen quality level.

Resize ​

Smart Cropping ​

When enabled, Optimole automatically detects the most important or interesting part of each image. When images are cropped or resized, the crop focuses on that region rather than defaulting to the center. This is useful for product images, portraits, or any content where the subject may not be centered.

Limit Image Sizes ​

When enabled, you can define maximum width and height values (in pixels) for images served on your site. Any image exceeding these dimensions is automatically scaled down while preserving its aspect ratio. The defaults are 1920 px wide and 4000 px tall. Note that enabling this feature disables retina (DPR) images to maintain consistent dimensions, which may result in slightly lower quality on high-resolution screens.

When toggled on, two number fields appear:

  • Width sets the maximum width (minimum 100, maximum 10,000).
  • Height sets the maximum height (minimum 100, maximum 10,000).

Add New Image Crop Size ​

Use this if you notice images are not cropped correctly after enabling Optimole. You can define custom crop sizes by entering a width and height, then clicking Add size. Each added size appears in the Your cropped image sizes list below, where you can remove it if no longer needed. This is only necessary when specific theme or plugin image sizes are not being handled correctly out of the box.

Lazyload ​

Enable Lazy Loading & Scaling ​

This is the main toggle for lazy loading. When enabled, images load only when they are about to enter the visitor's viewport, which reduces initial page load time. A confirmation dialog warns you about the potential performance impact before you can disable it.

When this toggle is off, the rest of the Lazyload page is hidden and only this single toggle is shown.

Loading Method ​

Choose how lazy loading is implemented:

  • Smart Loading (default) uses JavaScript-driven lazy loading with advanced controls including viewport detection, custom placeholder colors, and automatic image scaling. This is the recommended option for most sites.
  • Native Browser Loading (marked "Not recommended") uses the browser's built-in loading="lazy" attribute. It is lightweight and does not require JavaScript, but it does not support smart image scaling and offers fewer controls. A warning notice appears when this option is selected explaining the trade-offs.

Loading Method (Global) ​

Below the loading method radio boxes is a group of global checkboxes that control which images bypass lazy loading:

  • Skip lazy loading for first images lets you specify a number of images at the top of each page that load immediately without lazy loading, ensuring above-the-fold content appears instantly. A number field next to the checkbox controls how many images to skip (default is 2).
  • Skip images above the fold uses a lightweight client-side script to detect which images are visible in the initial viewport and loads those immediately. All other images lazy load normally.

When both options are enabled simultaneously, a notice explains the interaction: the fixed skip count applies on a visitor's first page view, and on subsequent views the viewport detection data takes priority.

Visual Settings ​

  • Enable generic placeholder color replaces the default blurry low-quality placeholder with a solid color during lazy loading. When checked, a color swatch button appears that opens a color picker where you can choose any color. Use the Clear button inside the picker to reset to the default transparent placeholder.
  • Enable <noscript> fallback provides fallback images for browsers that do not support JavaScript-based lazy loading. Disabling it may help resolve conflicts with other plugins and reduces HTML page size slightly. Leave it off unless you specifically need to support no-JavaScript environments.

Smart Image Scaling ​

When enabled, Optimole automatically resizes images based on the visitor's device and viewport dimensions, serving appropriately sized images rather than full-resolution originals. Disabling this shows a performance impact warning. This setting is independent of lazy loading and controls only the scaling behavior.

Extended Features ​

  • CSS Background Lazy Load applies lazy loading to images set as CSS background properties. The toggle enables it globally. When turned on, an optional text area labeled Extend CSS Background Images appears where you can list additional CSS selectors (one per line or comma-separated) for elements whose backgrounds should also be lazy loaded. If everything works out of the box, leave the text area empty.
  • Video & iframes enables lazy loading for embedded videos and iframe content (such as YouTube or Vimeo embeds). This defers loading these heavy resources until they scroll into view.

Exclusions ​

Don't optimize and don't lazy-load images if ​

This section lets you define rules for images that should be completely excluded from both optimization and lazy loading. Each rule is a combination of a filter type, an operator, and a value. You build rules using the dropdown and input controls, then click Add filter. Active exclusions are listed below and can be individually removed.

Filter types available:

  • Image filename contains a specified text string
  • Image extension is one of: SVG, JPG, PNG, GIF, or WEBP
  • Page URL contains a specified string, or matches an exact path (when set to "matches"). For the homepage, use the keyword home
  • Image class contains a specified CSS class name

Filter values must be at least 3 characters long.

Don't lazy-load images if ​

This section only appears when lazy loading is enabled.

This works identically to the optimization exclusion rules above, but only prevents lazy loading while still allowing Optimole to optimize and serve the image through the CDN. Use this when an image must load immediately (for example, a hero banner handled by a slider plugin) but should still benefit from compression and format conversion.

Cloud Library ​

Unified Image Access ​

When enabled, you can browse and use all images stored in your Optimole account from any website connected to that account, not just images uploaded to the current site. The images become available in the Cloud Library tab accessible via the Go to Cloud Library link that appears when this setting is on.

Show images only from these sites ​

This setting only appears when Unified Image Access is enabled and you are not using a sub-API key.

By default, the Cloud Library shows images from all sites connected to your Optimole account. Use this field to restrict it to specific sites. Type or select site domains from the suggestions provided. If left empty, images from all sites are shown.

Was this helpful?

Copyright (c) 2026 Optimole