NeoWish Documentation
All documentation · Plugin page · Download on WordPress.org · Support forum
1. Introduction
1.1 Welcome & Features
NeoWish adds a wishlist to WooCommerce. A shopper who is not ready to buy can save a product and come back to it, and you get to see which products are being saved most.
Two things set it apart from the usual wishlist plugin, and both matter more than they sound:
- Guests get a real wishlist, with no account required. When they later register or sign in, the guest list merges into their account rather than vanishing. Nothing is gated at the moment of interest, which is the moment stores usually lose people.
- It is safe behind a full-page cache. The button markup is identical for every visitor; the saved state arrives afterwards over the REST API. A cached page can never serve one shopper the hearts of another.
Everything in the free plugin, at a glance:
- Add to Wishlist button on the product page and the shop loop, with position and placement settings and a shortcode for anywhere else
- Guest wishlists under a secure token, with no personal data in the URL
- Guest-to-account merge on registration and login
- Variation-aware saving of the exact color or size chosen
- A wishlist page, created for you on activation, with add to cart per item
- Sharing by copy link, WhatsApp, X and Facebook, with a per-list privacy toggle
- A Most Wishlisted dashboard
- Design settings for colors and border radius
- Keyboard accessible, screen-reader announcements, RTL-ready and translatable
- HPOS compatible
1.2 System Requirements
| Requirement | Minimum |
|---|---|
| WordPress | 6.6 or higher |
| WooCommerce | 8.0 or higher |
| PHP | 7.4 or higher |
WooCommerce is required, not optional — NeoWish declares it as a plugin dependency, so WordPress will tell you if it is missing. High Performance Order Storage is supported either way, on or off.
2. Installation & Setup
2.1 How to Install
- In WordPress, go to Plugins → Add New.
- Search for NeoWish, or upload the zip from WordPress.org.
- Click Install Now, then Activate.
- Open Marketing → NeoWish to configure it.
2.2 What Happens on Activation
Activating NeoWish does three things, so there is nothing to set up before it works:
- Creates the wishlist page and puts the
[neowish]shortcode on it - Creates its own database tables for lists, items and anonymous events
- Shows the heart button on product pages and the shop grid with sensible defaults
From there every setting is optional. The rest of this page explains what each one changes.
3. The Button
3.1 Product Page Position
Marketing → NeoWish → Settings → Button Position (Product Page) decides where the heart appears on a single product page.
| Option | Where it lands |
|---|---|
| After the price | Directly beneath the price |
| Before the Add to Cart button | Above the add-to-cart form |
| After the Add to Cart button | Below the add-to-cart form (the default) |
| Hidden | Nothing is rendered; use the shortcode instead |
These anchor to WooCommerce's own template hooks rather than to fixed priorities, so they land correctly on classic themes, on themes that rebuild the product summary (Astra and the like), and on block themes. If a theme offers nothing to anchor to, the button falls back to the end of the product summary rather than disappearing — that also covers out-of-stock products, which render no add-to-cart form at all.
3.2 Shop Page Placement
Show Button on Shop & Archive Pages turns the heart on and off across the product grid, and Button Placement (Shop Page) decides where it sits on each card.
| Option | Result |
|---|---|
| Over the product image | A round heart in the top-left corner of the image. The default. |
| Beside the product name | The heart shares a line with the product title. |
Top-left is deliberate: WooCommerce puts the sale badge in the top-right corner, so the two never collide.
3.3 Button Style
Button Style controls what the button shows:
- Heart icon and text — the default
- Heart icon only
- Text only
On the shop grid the button is always icon-only regardless, to fit the card. The label is still there for screen readers.
3.4 Shortcodes
| Shortcode | Output |
|---|---|
[neowish] |
The full wishlist table. Already placed on the page created at activation. |
[neowish_button] |
An Add to Wishlist button for the current product. |
[neowish_button product_id="123"] |
A button for one specific product, usable anywhere. |
Set the product-page position to Hidden if you want to
place the button yourself with [neowish_button] and not have
a second one appear automatically.
4. Wishlists
4.1 Guests & the Merge
A visitor with no account gets a full wishlist immediately. It is stored against a secure random token in a cookie — no personal data goes into the URL, and the token is validated on every request.
When that visitor registers or logs in, their guest list merges into the account automatically. Items already saved to the account are not duplicated. Nothing is lost and nothing needs to be re-saved.
Guest Wishlist Lifetime (Days) under Settings controls how long a guest keeps their list before the browser forgets it. Logging in makes it permanent.
Since version 1.0.1, guest lists nothing can reach any more are also
cleaned up on the server: a daily background task removes guest lists
that have been idle for the whole cookie lifetime plus a 30-day
grace window, so a list is only ever deleted long after its cookie
could still have opened it. Lists that belong to an account are never
touched, whatever their age, and developers can change the window with
the neowish_guest_list_retention_days filter.
4.2 The Wishlist Page
The wishlist page is created for you on activation and holds the
[neowish] shortcode. If you move or rebuild it, point
Settings → Wishlist Page at the right page.
Each row shows the product, its price, whether it is in stock, and when it was saved. Two settings change what Add to Cart does from there:
- Remove Item After Adding to Cart — clears the item from the wishlist once it is in the cart
- Go Straight to Checkout From the Wishlist — sends the shopper to checkout instead of leaving them on the page
4.3 Sharing
A shopper can switch their list to Shared and send the link by copy, WhatsApp, X, Facebook or email. Guests can share too.
Sharing is off until the shopper turns it on, per list. A shared link carries an unguessable slug rather than a user id, and a list switched back to private stops resolving immediately.
5. Design & Reporting
5.1 Colors & Radius
The Design tab sets four things, and they belong to NeoWish alone — no other plugin overrides them:
| Setting | What it colors |
|---|---|
| Primary Brand Color | The saved heart, links and focus outlines |
| Accent/Success Color | The "Added to your wishlist" toast, in-stock labels and the copied-link confirmation |
| Text Color | Button and table text |
| Border Radius (px) | Corners on the button, toast and wishlist table |
The preview pane beside the pickers updates as you drag, so you can see the result before saving.
5.2 Most Wishlisted
The Dashboard tab reports what your customers are saving: how many wishlists hold something, how many items are saved in total, how many distinct products, and how many people saved something in the last 30 days — plus the Most Wishlisted table.
This is demand data you did not have before: products with many saves and few sales are usually a price or stock problem, not an interest problem.
5.3 NeoGrow Points
If NeoGrow is active, every wishlist row also shows the loyalty points that product would earn when bought, using NeoGrow's own earn rate including any bonuses. It turns a saved list into a reason to check out.
NeoWish is standalone and needs nothing else to work. This is a bonus when both are present.
6. Reference
6.1 Caching & Performance
NeoWish is built to sit behind a full-page cache without special rules. The button HTML contains no visitor-specific data at all — no saved state, no user id, no nonce. After the page loads, one REST request fetches the visitor's real state and marks the right hearts.
That state response is sent with Cache-Control: no-store, and
the wishlist page itself is sent with no-cache headers. The result is
cacheable product and shop pages with a correct, personal wishlist on top.
Wishlists live in their own tables rather than in post meta, so a large catalog with many saved lists does not slow down the rest of WordPress.
Version 1.0.1 tightened this further: the wishlist page loads every saved product in one batch instead of one query each (which matters most on long lists), background clean-ups run in small indexed batches, and a scheduler check that used to run a database query on every page view no longer does.
6.2 Hooks for Developers
The seams most often needed when adapting NeoWish to a theme or another plugin:
| Filter | Purpose |
|---|---|
neowish_button_position | Override the product-page position in code. |
neowish_button_position_hooks | Re-anchor the button for a theme neither the classic nor the block path fits. |
neowish_loop_placement | Override the shop-page placement in code. |
neowish_loop_title_hooks | Tell NeoWish which hooks bracket the product title in your theme's loop. |
neowish_settings_tabs | Add a tab to the NeoWish admin screen. |
neowish_settings_fields | Add a setting to an existing section. |
neowish_guest_list_retention_days | Change how long an idle guest list is kept before the daily clean-up removes it (default: cookie lifetime + 30 days). |
The plugin ships a HookDocs reference listing the full set,
including the item and list action hooks.
6.3 Frequently Asked Questions
Do guests lose their wishlist when they create an account?
No — that is the point of NeoWish. The guest wishlist merges into the new account automatically on registration or login, and duplicates are collapsed on the way in.
What happens to guest wishlists that are never claimed?
Since 1.0.1 they are cleaned up automatically. A guest list that stays idle for the whole cookie lifetime plus a 30-day grace window is removed by a daily background task — by then its cookie has long expired and nothing can reach it. Lists that belong to an account are never touched.
WooCommerce has its own wishlist experiment. Do I still need NeoWish?
Newer WooCommerce versions include an experimental wishlist that is off by default, works for logged-in customers only, keeps one fixed list, and renders through block templates. NeoWish works for guests from the first click, keeps the list through login, works in classic themes as well as block themes, remembers the exact variation, and adds sharing and the Most Wishlisted report. Both can be installed on the same site without conflict, because they store their data separately.
Does NeoWish work with caching plugins?
Yes, by design. The button markup is identical for every visitor and the personal state loads over the REST API, so cached pages never show the wrong hearts. The wishlist page itself is sent with no-cache headers.
Can customers save a specific variation?
Yes. Adding from a product page saves the selected variation, and the wishlist shows which one it was.
The button is in the wrong place on my theme.
On the shop page, switch Button Placement to
Over the product image — that placement is CSS-only
and does not depend on theme hooks. On the product page, try a different
position; if none of them land where you want, set the position to
Hidden and place [neowish_button] yourself.
Why do the dashboard statistics not update immediately?
They are cached for one hour so the admin stays fast. New activity is safe and appears at the next refresh.
Does the wishlist show loyalty points?
Only when NeoGrow is active. Each item then shows the points it would earn when purchased.
6.4 Uninstalling
Deactivating NeoWish leaves your data alone, so you can turn it off and back on without losing anything.
Deleting the plugin removes everything it created: the wishlist and item tables, the anonymous event table, and every option it registered. This cannot be undone, so export anything you want to keep first.