Appearance
Image Optimization
The Image Optimization function provides comprehensive image handling including client-side optimization, WebP conversion, watermarking, automatic SEO metadata, and a server-side bulk resize tool for your existing media library.
Overview
This feature combines two powerful capabilities: real-time client-side image optimization during upload, and a bulk resize tool for optimizing existing images in your media library. Images are processed before upload to reduce server load and storage costs.
Key Features
- Client-side image resizing before upload
- WebP conversion for smaller file sizes
- Configurable maximum dimensions and quality
- Text or image watermark support
- Automatic SEO-friendly alt text generation
- Smart file renaming based on post titles
- Disable WordPress auto-scaling
- Toast notifications during optimization
- Bulk resize tool for existing media
- Batch processing with progress tracking
- Optimization status column in media library
Setup Instructions
Step 1: Enable the Function
- Navigate to Voxel Toolkit → Functions in your WordPress admin
- Find Image Optimization in the list
- Toggle the switch to enable
Step 2: Configure Settings
- Click the settings icon next to Image Optimization
- Configure your preferred optimization settings
- Save your changes
Configuration Settings
Image Processing
| Setting | Description | Default |
|---|---|---|
| Max File Size | Maximum file size in MB (larger files are compressed) | 10 MB |
| Max Width | Maximum image width in pixels | 1600 px |
| Max Height | Maximum image height in pixels | 1600 px |
| Output Quality | JPEG/WebP compression quality (1-100) | 80% |
| Optimization Mode | How to handle different image formats | All to WebP |
SEO & Naming
| Setting | Description | Default |
|---|---|---|
| Rename Format | How to rename uploaded files | Post Title |
| Set Alt Text | Auto-generate SEO-friendly alt text | Yes |
| Alt Text Format | Format for auto-generated alt text | Title + Counter + Date |
Alt Text Formats
- Title Only: “My Post Title”
- Title + Counter: “My Post Title – Image 01”
- Title + Date: “My Post Title (January 13, 2026)”
- Title + Counter + Date: “My Post Title – Image 01 (January 13, 2026)”
Watermark Settings
| Setting | Description | Default |
|---|---|---|
| Watermark Type | None, Text, or Image watermark | None |
| Watermark Text | Text to display (if type is Text) | Empty |
| Watermark Image | URL of watermark image (if type is Image) | Empty |
| Position | Corner position for watermark | Bottom Right |
| Scale | Watermark size as percentage of image | 15% |
| Apply Watermark On | All uploads across the site, or post submission forms only | All uploads |
| Apply Watermark To These Fields | Per-field checkboxes: avatar, logo, featured image, gallery, cover, generic | All ticked |
Choosing where the watermark applies
By default the watermark is applied to every image uploaded anywhere on the site — not just listing photos, but timeline posts, message attachments, review images and anything added through the WordPress media library.
Set Apply Watermark On to Post submission forms only to restrict it to Voxel create and edit post forms.
Note that a Voxel profile is edited through a create post form too, so this setting on its own will not spare avatars and covers. That is what the field checkboxes are for.
Choosing which fields are watermarked
Untick any field you want left clean. A typical directory setup watermarks listing photos but not people:
| Field | Typical setting |
|---|---|
| Gallery Images | ticked |
| Featured/Thumbnail Image | ticked |
| Generic Image Field | ticked |
| Avatar (User Profile) | unticked |
| Cover Image | unticked |
| Logo (Business/Listing) | unticked |
Fields are matched by their key. If a field cannot be identified it follows the Generic Image Field setting.
Listing covers and profile covers share a setting
Both are matched as cover, so they cannot be watermarked differently from one another.
Other Settings
| Setting | Description | Default |
|---|---|---|
| Disable WP Scaling | Prevent WordPress from creating scaled versions | Yes |
| Show Toast | Display notification during optimization | Yes |
Bulk Resize Tool
The Bulk Resize tool allows you to optimize existing images in your media library that were uploaded before enabling Image Optimization.
Accessing Bulk Resize
- Navigate to Media → Bulk Resize (VT) in WordPress admin
- Configure target dimensions and quality
- Select images to process or run on all unoptimized images
- Start the batch process
Bulk Resize Features
- Batch Processing: Process multiple images automatically
- Progress Tracking: Visual progress bar and status updates
- Size Comparison: See before/after file sizes
- Status Column: Media library shows optimization status
- Safe Processing: Original images are backed up
Use Cases
User-Generated Content
Automatically optimize images uploaded by users through frontend forms without requiring manual intervention.
Photography Sites
Add watermarks to protect your images while maintaining quality with configurable compression.
SEO Optimization
Automatically generate descriptive alt text and file names to improve image SEO.
Storage Optimization
Reduce storage costs and improve page load times by converting to WebP and limiting maximum dimensions.
Legacy Media Cleanup
Use bulk resize to optimize thousands of existing images uploaded before optimization was enabled.
Troubleshooting
Every Upload Is Saved Twice
Fixed in 1.9.2. Uploads made through the WordPress media modal produced two attachments — your untouched original and the optimized, renamed copy. It affected every image type, though it is most noticeable with WebP, where both copies keep the same extension and look identical side by side.
To clean up pairs already in your library: keep the copy whose filename follows your Rename Format setting, and delete the one that kept its original filename. The renamed copy is the one attached to your post, so removing the other is safe.
Images Not Being Optimized
- Verify the function is enabled
- Check that JavaScript is loading without errors
- Ensure the image exceeds the file size threshold
- Clear browser cache
Media → Add New before 1.9.2
That screen builds its uploader differently from the rest of wp-admin, and the optimizer never attached to it — images uploaded there were stored full size, unrenamed and unwatermarked, with no error to indicate it had been skipped. Fixed in 1.9.2. Images uploaded there earlier can be reprocessed with the Bulk Resize Tool.
Watermark Not Appearing
- Check watermark type is set to Text or Image
- Verify watermark text or image URL is provided
- Ensure watermark image URL is accessible
- Try increasing the watermark scale
- Check the field is still ticked under Apply Watermark To These Fields
- If Apply Watermark On is set to Post submission forms only, uploads made through the WordPress media library are skipped by design
Alt Text Not Generated
- Enable the “Set Alt Text” option
- Ensure the image is attached to a post (for post title fallback)
- Alt text is set server-side after upload completes
Bulk Resize Fails
- Check PHP memory limits
- Increase PHP max execution time
- Process smaller batches
- Check server error logs
Requirements
- Modern browser with Canvas API support
- JavaScript enabled
- GD or Imagick PHP extension (for bulk resize)