Cliffjumper — WooCommerce Swatch Dropdown

Cliffjumper replaces standard WooCommerce variation dropdowns with a modern, image-first swatch dropdown. It’s built for store owners who want visual, fast, and mistake-proof option selection (e.g., color chips with thumbnails) while keeping the native WooCommerce variation flow intact.

Version: 1.0.2
Author: Eric Kowalewski
Requires: WordPress 6.x+, WooCommerce 7.x/8.x+, PHP 8.0+

✨ Features

• Visual swatch dropdowns: Show color chips and/or thumbnails alongside attribute labels.
• Zero theme lock-in: Enhances WooCommerce’s native variation UI; falls back gracefully to default selects.
• Keyboard & screen-reader friendly: Preserves accessibility of standard selects.
• Lightweight: Minimal JS/CSS, no jQuery dependency.
• Works with existing attributes: No data migration required.

📦 Installation

Option A: WordPress Admin

1. Go to Plugins → Add New → Upload Plugin.
2. Upload cliffjumper-v1.0.2.zip.
3. Click Install Now, then Activate.

Option B: Manual (FTP/SSH)

1. Extract the zip to wp-content/plugins/cliffjumper/.
2. Activate Cliffjumper in Plugins.

Tip: Clear any page cache/asset cache after activation (hosting cache, Cloudflare, WP Rocket, etc.).

⚙️ Quick Setup

1. Create/Edit Attributes

   • WooCommerce → Products → Attributes (e.g., Color).
   • Add terms (e.g., Navy, Charcoal, Maroon).

2. Add Images/Swatches to Terms

   • Edit each attribute term and assign a representative color value or image (if your site uses thumbnail fields for terms).
   • If your theme/plugins don’t add term images, Cliffjumper will still work with labels; images are optional.

3. Use the Attribute on Products

   • In a variable product, add your attribute to Variations as usual.
   • Cliffjumper will automatically enhance the variation dropdown on the product page.

🧩 How It Works

• Cliffjumper watches WooCommerce variation select elements (e.g., attribute_pa_color) and renders a compact, searchable dropdown with:

  • Chip (color preview) and/or thumbnail (term image),
  • Term label, and
  • Optional tooltips (if present on the term).

• Selecting a swatch updates the underlying native select, so stock checks and variation changes keep working exactly as WooCommerce intends.

🎛️ Settings (If Available)

Check WooCommerce → Settings → Products → Cliffjumper (or Settings → Cliffjumper) for:

• Enable on these attributes (e.g., Color, Size),
• Prefer term color vs. image,
• Show labels next to chips,
• Compact mode for mobile.

If you don’t see a settings page, Cliffjumper may ship with sensible defaults. Tell me your preferred options and I’ll wire the docs to match your build.

🧪 Compatibility

• Themes: Works with most themes that do not radically replace the variation UI. Tested with popular WooCommerce themes.
• Plugins: Designed to play nice with inventory/variation plugins that rely on native selects.

If your theme fully replaces the variation form, Cliffjumper will gracefully fall back to stock selects.

🛠️ Developer Notes

Cliffjumper is designed to be theme-agnostic and hook-friendly.

• Selectors: Enhances Woo standard variation selects inside .variations_form.
• Fallback: If no supported attributes are present, the native Woo UI remains.

Do you have specific hooks/filters in this build (e.g., to map term → image/color, supported attribute list, or markup overrides)? Share their names and I’ll document them here with examples.

📚 FAQ

Will this break my product variations or stock logic?
No. Cliffjumper reads/writes the underlying select value. WooCommerce still controls variation availability, price, and stock.

Do I need to re-create attributes?
No. Use your existing attributes and terms.

What if a term doesn’t have an image?
Cliffjumper shows the term label (and color chip if available). You can mix labels+chips+images.

Can I limit Cliffjumper to only Color?
Yes—either via settings (if included) or a small snippet/filter. Tell me your preference and I’ll add the exact example.

🧯 Troubleshooting

• Swatches not appearing

  • Ensure the product is variable and attributes are enabled for variation.
  • Clear all caches and hard-refresh the page.
  • Confirm no theme/plugin is fully replacing the .variations_form HTML.

• Term images don’t show

  • Make sure term images (or color meta) are actually set on the attribute term.
  • If term images come from another plugin, confirm their meta keys; we can add a mapping snippet.

• Mobile layout issues

  • Some themes add tight CSS to .variations_form. A small CSS override usually fixes this. Share a URL if you want me to include a ready-made snippet.

🚀 Roadmap

• Per-attribute display controls (chips only / image only / label only)
• Quick term image picker in the product editor
• Global palette presets for color attributes
• Inline search for long attribute lists

🔄 Changelog

• 1.0.2 — Current release with stability and UX refinements.
• 1.0.1 — Minor fixes and compatibility improvements.
• 1.0.0 — Initial public release.

🤝 Contributing

Issues and PRs welcome! Please include:

• Steps to reproduce,
• Screenshots/screencasts,
• Theme name + WooCommerce version.

📜 License

Choose a license (e.g., GPL-2.0+ for WordPress plugins).
If you tell me the license you prefer, I’ll fill this in properly.

👤 Author

Eric Kowalewski
The Bear Traxs • Michigan, USA