• Overview
• Installation
  • Using an S3 Source
• Configuration and functions
• Using imgix without a plugin (Asset Manager)
• FAQ
  • Using imgix URLs for previous images

Overview

The wp-imgix plugin is a lightweight, community-maintained plugin that allows imgix to serve and transform images on your WordPress site.

If you want to manage your images within the WordPress CMS, we recommend using wp-imgix.

Installation

Before you begin, you need to create an imgix Source. We recommend creating an S3 Source and combining that with S3-Uploads for your WordPress & imgix integration

1. Upload and enable wp-imgix.
2. Add define( WP_IMGIX_URL, your.imgix.net ) to your wp-config.php file.
3. If you're signing URLs, Add define( WP_IMGIX_SIGNING_TOKEN, abcdefg123456 ) to your wp-config.php file.

Using an S3 Source

We strongly recommend installing S3-Uploads, which allows you to offload your images to S3. There are several benefits to offloading your images and uploads to S3:

• Files stored in S3 tend to be more reliably delivered via the imgix service than files stored in the default wp-uploads folder.
• Using an S3 Source gives you automatic access to Asset Manager in imgix
• Offloading files can potentially save you server space for your WP installation

Once you offload all your assets to S3, you can create an S3 imgix Source to use in your wp-config.php file (see step #2 under the installation steps)

Configuration and functions

Typically the above steps are all you need to do; however, you can use the following public-facing functions and filters. For more information on modifiable functions and filters, visit the plugin's GitHub repo.

Using imgix without a plugin (Asset Manager)

The Asset Manager allows you to use imgix in WordPress posts and pages (not thumbnails or featured images) without needing to install any other plugins. The only requirement is that you use an Asset Manager compatible Source (S3/GCS/Azure).

Once you've configured Asset Manager so that you can upload images into your bucket, you can click on an image to bring up the details pane. Click the </> icon to copy an image embed code.

You can paste this embed code as HTML in WordPress to render an image.

The generated embed code is an image tag with the srcset attribute. The srcset provides the browser with a list of images. From this list, the browser will take the user's device pixel ratio and the sizes attribute and calculate a single image resolution for the user's device.

Note that the Asset Manager does not provide the sizes attribute. Unless you expect your image to be 100% the width of your page, it is essential that you define a sizes attribute that matches the rendered size of your image. Otherwise, your image performance may worsen.

As an example, we copied an image embed from the Asset Manager. Additionally, we added sizes="(min-width: 780px) 780px, 100vw" because we expect the max size of the image to be 780px on this page:

<img
  class="ix-embed-image"
  srcset="https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=100 100w, https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=116 116w,
  https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=134 134w, https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=156 156w, 
  https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=182 182w, https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=210 210w, 
  https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=244 244w, https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=282 282w, 
  https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=328 328w, https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=380 380w, 
  https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=442 442w, https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=512 512w, 
  https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=594 594w, https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=688 688w, 
  https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=798 798w, https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=926 926w, 
  https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=1074 1074w, https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=1246 1246w, 
  https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=1446 1446w, https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=1678 1678w, 
  https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=1946 1946w, https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=2258 2258w, 
  https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=2618 2618w, https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=3038 3038w, 
  https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=3524 3524w, https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=4088 4088w, 
  https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=4742 4742w, https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=5500 5500w, 
  https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=6380 6380w, https://assets.imgix.net/examples/blueberries.jpg?auto=format,compress&w=7400 7400w" 
  src="https://assets.imgix.net/examples/blueberries.jpg?ixembed=1663104424109&auto=format,compress"
  sizes="(min-width: 780px) 780px, 100vw"
/>

When pasted into WordPress, it will generate this image:

FAQ

Using imgix URLs for previous images

The wp-imgix plugin automatically changes the image URL so that all your current and new images get served via imgix.

If, for whatever reason, you are still serving images with an old URL and you wish to use imgix for all your WordPress URLs, follow the steps below:

NOTE: Before proceeding, please make a backup of your WordPress site and your database. Failure to do so can leave your WordPress database in an unrecoverable state

1. Install wp-imgix first

• If you are using S3-Uploads, upload a few images and make a note of the folder structure in S3
• (ONLY Upload the rest of your WordPress images to your S3 bucket, making sure to clone the folder structure in your S3

1. Do a find and replace in your WP database (instructions vary on how to do this - you can try exporting the database → editing it with a code editor → import it back)
   • Back up your database before performing any find and replace operations. Failing to do so may prevent you from restoring your data if you make a mistake.
2. Look for old image BASE paths (ex: www.WordPresssite.com/wp-content/uploads/)
3. Replace with your new imgix path (ex: subdomain.imgix.net/wp-content/uploads/)
4. Save and apply
5. This should update all your old image URLs with your new imgix URLs

These are the general instructions for converting WordPress image URLs to imgix. Depending on your WordPress setup, you may need to do more than just edit the database values.