=== ShopShelf – Product Grid & Carousel for WooCommerce ===
Contributors: shshakib2001
Tags: woocommerce, product grid, product carousel, product slider, product list
Requires at least: 5.7
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.3.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Show WooCommerce products in a responsive product grid, carousel or list, with live filters, ready-made templates, a block and Elementor widgets.

== Description ==

**ShopShelf is a WooCommerce product grid, product carousel and product list plugin.** Pick the products, choose how they look, and place the result on any page, post or widget with a block, an Elementor widget or a shortcode.

WooCommerce's own shop page shows every product the same way, in one place. ShopShelf lets you build as many product displays as you need: best sellers on the home page, a sliding row of sale items on a landing page, a category grid with live filters, or a compact list in a blog post. Each one has its own products, layout and style.

You build a **layout** (one saved product display) in three steps:

1. **Choose the products.** Use all products, or only featured, on-sale, best-selling, top-rated or free ones. You can narrow them by category, tag or attribute.
2. **Choose the look.** Pick Grid, Carousel or List. Then use a ready-made card template, or build your own card by turning parts on and off and dragging them into order.
3. **Place it.** Add the ShopShelf Layout block, an Elementor widget or the layout's shortcode wherever you want the products to appear.

A live preview shows the result at desktop, tablet and mobile sizes while you edit.

= Why ShopShelf =

* **Three layouts in one plugin.** Grid, Carousel and List, so you do not need separate plugins for a product grid and a product slider.
* **Shoppers can filter without reloading.** Category buttons, dropdowns and a search box update the products instantly. Load More, AJAX pages and infinite scroll work the same way.
* **Ready-made templates or your own design.** Start with a template, or control every part of the card down to the meta fields and typography.
* **Works with the editor you use.** It has a native Gutenberg block, four Elementor widgets and a shortcode for everything else.
* **Self-contained.** Scripts, styles, icons and fonts are served from your own site, with no external requests, and the scripts load only on pages that show a layout.

= Three layouts =

* **Product Grid** — products in rows and columns, with a column count for each of five screen sizes
* **Product Carousel** — the same cards on a sliding track, in three modes: Standard, Center and Ticker
* **Product List** — horizontal product cards with the image beside the details, in one or more columns, with the image on the left or right, an adjustable image width, and an option to stack on mobile

= Pre-made templates =

Every layout can use your own card design or one of three ready-made product card templates:

* **Template One** — the price shown in a block on the product image
* **Template Two** — an Add to Cart button that appears over the image on hover
* **Template Three** — a classic shop card with the price and button side by side

Each template has its own options: which parts to show, image size, title and description length, button type and label, text alignment, star rating, a Sale / Featured badge and colour-coded stock status. A Theme Color Scheme sets the accent colour, with a second colour for featured products.

= Choose your products =

* Draw from all products, or only featured, on-sale, best-selling, top-rated or free ones
* Limit to simple, variable, grouped or external products
* Show a set number of products
* Include only specific products, or exclude specific ones
* Filter by product category, tag or any product attribute, with IN / AND / NOT IN operators
* Hide out-of-stock, on-sale, free or image-less products, and show or hide catalog-hidden ones
* Sort by date, title, price, popularity, rating, modified date, menu order, ID or at random

= Live product filters for shoppers =

* Filter by category, tag or attribute, shown as buttons, a dropdown, radio buttons or checkboxes, with optional product counts
* A keyword search box
* Results update with AJAX, without reloading the page
* Load More button, AJAX numbered pages, infinite scroll or ordinary page links for grids and lists

= Build your own product card =

Drag the parts of a product card into the order you want and switch off the ones you do not need:

* Product image, at any registered size or a custom cropped size
* Title, with your choice of HTML tag and a length limit
* Meta fields — category or tag, star rating, SKU, stock status, stock quantity, units sold, weight, dimensions and date
* Description — the short description, a trimmed description or the full one
* Price, with a separate colour for the struck-through regular price
* Add to Cart, Read More button or Read More text link
* Social share links for Facebook, X (Twitter), LinkedIn, Pinterest and email

= Responsive design and styling =

* Columns and gap per screen size, and equal card heights
* Card border, corner radius, shadow, background and inner padding
* Typography for every text element, with separate sizes for desktop, tablet and mobile
* A site-wide colour scheme that every layout falls back to
* Custom CSS and JavaScript, kept safe from theme and plugin updates

= Carousel controls =

* Autoplay with pause on hover, speed and infinite loop
* Slide, fade, coverflow, cube and flip transitions
* Multiple rows, and slides-to-scroll per screen size
* Navigation arrows in nine positions, with a choice of icons and colours
* Dot or numbered pagination, with dynamic bullets
* Keyboard navigation, touch swipe, mouse drag and mouse wheel
* Editable screen-reader messages

= Works with your editor =

* **Block editor** — the ShopShelf Layout block picks a saved layout and previews it in the editor, in posts, pages and templates
* **Elementor** — Product Grid, Product Carousel and Product List widgets with the full set of product, filter, card and carousel options plus Elementor's own style controls, and a Saved Layout widget for layouts built in ShopShelf
* **Anywhere else** — a shortcode for the classic editor, text widgets, other page builders and theme templates

= Built to stay out of the way =

* A live preview while you edit — including before you save
* Templates you can override from your theme
* Every setting is scoped to its layout, so two showcases on one page can look completely different
* All scripts, styles, icons and fonts are served from your own site
* Sample layouts, a settings backup and a system status report under Tools
* A built-in Help screen documenting every control

= Source code =

The plugin ships the human-readable source of everything it minifies:

* Front end: `src/Frontend/assets/js/scripts.js`, `elementor.js` and `src/Frontend/assets/css/style.css` / `shopshelf-grid.css` sit beside their `.min` versions.
* Block: the source of `src/Admin/assets/block/` is in the `shopshelf-block/` folder. To rebuild it, run `npm install` and `npm run build` inside that folder (Node.js 20 or newer).
* Admin: the React source of `src/Admin/assets/app/shopshelf-admin-app.js` is in the `shopshelf-admin/` folder. To rebuild it, run `npm install` and `npm run build` inside that folder (Node.js 20 or newer).

Bundled third-party libraries:

* [Swiper](https://github.com/nolimits4web/swiper) 14.3.0 — MIT License. Both `swiper-bundle.js` and `swiper-bundle.min.js` are the unmodified files from the official package.
* [IcoFont](https://icofont.com/) — the font is licensed under the SIL Open Font License 1.1 and its CSS under the MIT License.
* The admin bundle includes [React](https://github.com/facebook/react), [React Router](https://github.com/remix-run/react-router), [Radix UI](https://github.com/radix-ui/primitives), [Lucide](https://github.com/lucide-icons/lucide), [Tailwind CSS](https://github.com/tailwindlabs/tailwindcss), [date-fns](https://github.com/date-fns/date-fns), [React Day Picker](https://github.com/gpbl/react-day-picker), [react-colorful](https://github.com/omgovich/react-colorful), [class-variance-authority](https://github.com/joe-bell/cva), [clsx](https://github.com/lukeed/clsx) and [tailwind-merge](https://github.com/dcastil/tailwind-merge), all under the MIT or ISC licenses. The full list with versions is in `shopshelf-admin/package.json`.

== Installation ==

1. Install and activate WooCommerce, if you have not already.
2. Go to **Plugins → Add New**, search for "ShopShelf", and click **Install Now** — or upload the plugin zip there.
3. Activate the plugin.
4. Go to **ShopShelf → Add New Layout**. Choose Grid, Carousel or List, pick your products under **Filter Settings**, set the look under **Display Options**, and publish.
5. Add it to a page: insert the **ShopShelf Layout** block and choose the layout, use the ShopShelf widgets in Elementor, or paste the layout's shortcode, for example `[shopshelf id="12"]`.

**Quick start:** go to **ShopShelf → Tools** and click **Add sample layouts** to create a ready-made Grid, Carousel and List from your own products, then edit them as you like.

== Frequently Asked Questions ==

= Does this require WooCommerce? =

Yes. ShopShelf displays WooCommerce products and calls WooCommerce directly, so it needs WooCommerce installed and active.

= Is ShopShelf free? =

Yes. Every feature described on this page is included in the free plugin.

= How do I display WooCommerce products with ShopShelf? =

Create a layout under **ShopShelf → Add New Layout**, choose the products and the design, and publish it. Then show it with the **ShopShelf Layout** block, a ShopShelf Elementor widget or the layout's shortcode, as described below.

= Can I create a WooCommerce product carousel or slider? =

Yes. Choose the **Carousel** layout. It has three modes (Standard, Center and Ticker), autoplay, five transition effects, arrows, dots and multiple rows, and you set the number of visible products for each screen size.

= Can I show products from one category? =

Yes. Under **Filter Settings → Advanced Filtering**, switch on **Taxonomy**, choose **Category** and pick the categories to include. Tags and product attributes work the same way. Turn on **Show as Live Filter** to let shoppers switch between those categories on the page.

= Is ShopShelf responsive? =

Yes. Columns, rows, slides to scroll and font sizes are set separately for each screen size, and the live preview lets you check the layout at desktop, tablet and mobile widths before you publish.

= Can I customize how the products look? =

Yes. Choose one of the three pre-made templates, or select **Custom** to build the card yourself: reorder its parts, choose which ones appear, and style borders, spacing, colours and typography. For anything else, add your own CSS under **Settings → Custom CSS & JS**.

= How do I show a layout? =

In the block editor, insert the **ShopShelf Layout** block and choose a layout from its list; it previews in the editor. An existing `[shopshelf]` shortcode or Shortcode block can be converted to it from the block toolbar.

Each layout also has a shortcode, shown in the layouts list and in the editor: `[shopshelf id="12"]`. Paste it into the classic editor, a text widget or a page builder's shortcode element. In a theme template, use `<?php echo do_shortcode( '[shopshelf id="12"]' ); ?>`.

= Can I use it with Elementor? =

Yes. With Elementor active, the **ShopShelf** category in the widget panel has four widgets:

* **Product Grid**, **Product Carousel** and **Product List** — build the showcase right in Elementor, with the same product, filter, card, template, pagination and carousel options as the layout editor, styled from Elementor's Style tab (responsive, and using your kit's global colours and fonts). They do not create a saved layout.
* **Saved Layout** — show a layout built under ShopShelf → Layouts.

Live filters, Load More and other pagination work in all of them.

= My layout shows no products. =

Check that the layout is published, then look at its filters: almost always they are narrower than the catalogue — a category with nothing published in it, or a Best Selling or Top Rated source on a shop with no sales or reviews yet. Clear the filters one at a time and preview after each.

= Can I put several layouts on one page? =

Yes. Each layout is wrapped in its own element and its settings, filters and pagination are scoped to it.

= Can I style one layout with my own CSS? =

Yes. Every layout is wrapped in an element with its own id, so a rule that starts with that id affects only that layout:

`#shopshelf_wrapper-12 .shopshelf__item--title a { text-transform: uppercase; }`

Add it with WordPress's own CSS editor: **Appearance → Customize → Additional CSS**, or **Styles → Additional CSS** in the Site Editor.

= Can I change the markup? =

Yes. Copy any template from the plugin's `src/Frontend/templates` folder into a `shopshelf` folder in your theme, keeping the same path — for example `yourtheme/shopshelf/item/title.php` — and edit it there. Your copy is used instead of the plugin's and survives plugin updates. **Tools → System status** lists any overrides it finds, which is worth checking if a setting seems to have no effect.

= Does the plugin load anything from other websites? =

No. Scripts, styles, icons and fonts are all served from your own site. The only outbound links are the optional social share links described under "External services" below, and they do nothing until a visitor clicks one.

= What happens to my layouts if I remove the plugin? =

Deactivating the plugin keeps everything. Deleting it from the Plugins screen removes its layouts and settings.

= Where can I get help? =

Open **ShopShelf → Help** in your dashboard for a guide to every setting. If you are still stuck, post in the [support forum](https://wordpress.org/support/plugin/shopshelf/) and include the report from **ShopShelf → Tools → System status**.

== Screenshots ==

1. WooCommerce product grid with live category filter buttons, a search box, Featured and Sale badges, star ratings and a Load More button.
2. WooCommerce product carousel (slider) with navigation arrows and dot pagination. This one uses Template Two, which shows Add to Cart over the image on hover.
3. Product list layout: horizontal product cards with the image beside the title, description, price and Add to Cart button.
4. The three pre-made product card templates side by side: price on the image, button on the image, and a classic shop card.
5. Choose Custom or Pre-made, pick a card template from its preview, and set its accent colours, alignment and image size.
6. Product selection: show all products, or only featured, on-sale, best-selling, top-rated or free ones, with include and exclude lists.
7. Advanced filtering: filter by category, tag or attribute, and show it to shoppers as buttons, a dropdown, radio buttons or checkboxes.
8. Gutenberg block: insert the ShopShelf Layout block, choose a saved layout and see it previewed in the block editor.
9. Elementor integration: Product Grid, Product Carousel, Product List and Saved Layout widgets, with a live preview in the editor.
10. Display options: columns for five screen sizes, gap between cards, equal card heights, and card border, corner radius and shadow.
11. Drag-and-drop card builder: reorder or switch off the image, title, meta fields, description, price, button and share links.
12. Carousel controls: Standard, Center and Ticker modes, autoplay, speed, loop, direction, transition effects and rows per screen size.
13. Typography: font family, style, size and line height for desktop, tablet and mobile, with colours for every text element.
14. Live preview: check a layout at desktop, tablet and mobile sizes while you edit, before you save.

== External services ==

This plugin does not connect to any external service by itself. It loads no remote scripts, styles, fonts or images, and it sends no data anywhere.

If you switch on **Social Share** for a layout, each product card shows ordinary links to the share pages of the networks you chose. No request is made to any of these services when the page loads. A link is opened only when a visitor clicks that share button, and at that moment the product's public URL and its title are passed to the service in the link's address so the service can prefill the post. No other data is sent by the plugin. What the service does after the visitor arrives there is governed by that service's own terms and privacy policy.

= Facebook =

Facebook's sharing dialog (`https://www.facebook.com/sharer/sharer.php`), provided by Meta Platforms, lets the visitor post the product link to Facebook. Opened only when the visitor clicks the Facebook share button. Data sent: the product URL.
[Terms of Service](https://www.facebook.com/legal/terms) · [Privacy Policy](https://www.facebook.com/privacy/policy/)

= X (Twitter) =

X's post composer (`https://twitter.com/intent/tweet`, which redirects to x.com), provided by X Corp., lets the visitor post the product link to X. Opened only when the visitor clicks the X share button. Data sent: the product URL and the product title.
[Terms of Service](https://x.com/en/tos) · [Privacy Policy](https://x.com/en/privacy)

= LinkedIn =

LinkedIn's share page (`https://www.linkedin.com/sharing/share-offsite/`), provided by LinkedIn Corporation, lets the visitor share the product link on LinkedIn. Opened only when the visitor clicks the LinkedIn share button. Data sent: the product URL.
[User Agreement](https://www.linkedin.com/legal/user-agreement) · [Privacy Policy](https://www.linkedin.com/legal/privacy-policy)

= Pinterest =

Pinterest's pin-creation page (`https://www.pinterest.com/pin/create/button/`), provided by Pinterest, Inc., lets the visitor save the product as a pin. Opened only when the visitor clicks the Pinterest share button. Data sent: the product URL and the product title.
[Terms of Service](https://policy.pinterest.com/en/terms-of-service) · [Privacy Policy](https://policy.pinterest.com/en/privacy-policy)

= Email =

The Email share button is a `mailto:` link. It opens the visitor's own email application with the product title as the subject and the product URL as the message body. Nothing is sent to any service by the plugin.

== Changelog ==
= 1.3.2 - 12 November 2026 =
* New: Skeleton Loading — placeholder product cards, shaped like the layout's own cards, shown while products load. Off by default; turn it on under Settings → Loading Effects.
* New: Loading Effects settings — Skeleton Animation (Shimmer, Pulse or None), Skeleton Background and Highlight colours, Number of Skeleton Items and Skeleton Border Radius.
* Improved: Loading experience for live filters, keyword search, AJAX pagination, Load More and infinite scroll in Grid, Carousel and List layouts, including the ShopShelf Layout block and the Elementor widgets.
* Improved: Placeholders follow each layout's responsive columns, card height, List image side and Stack on Mobile, and a carousel's slides per view, so the page does not jump when products arrive.
* Improved: Placeholders are hidden from screen readers, the product area is marked busy while it loads, and the animation stops for visitors who prefer reduced motion. If a request fails, the products that were on screen come back.
* New: `shopshelf_skeleton_settings` filter, and `shopShelfFrontend.skeletonCards` for add-ons that bring their own layouts.

= 1.3.1 - 07 November 2026 =
* Changed: Rewrote the plugin description, with a short overview, a "Why ShopShelf" section, a section on the pre-made templates and a quick-start tip in Installation.
* Changed: New screenshots for the plugin page, now including the List layout, the pre-made templates, the Gutenberg block and the Elementor widgets.
* Changed: More answers in the FAQ — product carousels, showing one category, responsive layouts, customising cards and where to get help.
* Fixed: The FAQ said there were three Elementor widgets; there are four, including Product List.
* No changes to plugin code, settings or saved layouts.

= 1.3.0 - 06 November 2026 =
* New: List layout — horizontal product cards with the image beside the title, price, description and button, in responsive columns (two by default), with Image Position, Image Width and Stack on Mobile options. Works with filters, pagination, the pre-made templates, the ShopShelf Layout block and a new Product List widget for Elementor.
* New: Pre-made templates for Grid, Carousel and List — three ready-made product cards: price on the image, Add to Cart over the image on hover, and a classic shop card — each with a preview image.
* New: Pre-made template options in place of Card Content: parts to show, image size, title and description length, button type and label, alignment, star rating, Sale / Featured badge and colour-coded stock status.
* New: Theme Color Scheme for pre-made templates, with a separate colour for featured products, and defaults under Settings → Color Scheme.
* New: Rating as a meta field in Card Content.
* New: Elementor's Product Grid and Product Carousel widgets offer the pre-made templates too.
* New: `shopshelf_premade_flag` filter, and pre-made templates you can override from your theme, under `shopshelf/theme/`.
* Changed: Display Options is now organised into General, Template Styles and Pagination tabs. Saved layouts are not changed.

= 1.2.0 - 03 November 2026 =
* New: ShopShelf Layout block for Gutenberg with saved layout previews, edit/create links, and shortcode conversion support.
* New: Elementor widgets — Product Grid, Product Carousel, and Saved Layout.
* New: Comprehensive Elementor Style controls for product elements, filters, pagination, and carousel navigation, including responsive styling and global fonts/colors.
* New: AJAX-powered live filters, Load More, AJAX pagination, and infinite scroll.
* New: shopshelf_ajax_view filter for custom AJAX layout integrations.
* Fixed: Carousel compatibility issues caused by conflicting Swiper versions from themes and other plugins.

= 1.1.0 - 01 October 2026 =
* New: Settings → Custom CSS & JS, with code editors for your own styles and scripts. Custom CSS loads after ShopShelf's styles; custom JavaScript runs only on pages that show a layout. Only users who may add unfiltered HTML can change it.
* New: `shopshelf:ready` and `shopshelf:products-loaded` jQuery events, fired when a layout starts and after filters, pagination or Load More bring in new products.
* New: Filter Products — draw from all products, or only featured, on-sale, best-selling, top-rated or free ones.
* New: Product Type filter — simple, variable, grouped or external products.
* New: Show Hidden Products, and options to hide out-of-stock, on-sale, free and image-less products.
* New: Order By and Order, including price, popularity and average rating.
* Changed: "Product Selection" is now "Filter Settings", reorganised into Products, Visibility & Stock, Order & Limit and Advanced Filtering.
* Changed: Clearer titles, descriptions and help text throughout the admin, with consistent terms.
* Changed: Defaults for new layouts — a light card border, a full-width product image, meta fields shown (category and stock status) and rounded carousel arrows. Saved layouts are not changed.
* Changed: Products set to Hidden or Search results only in WooCommerce are no longer shown unless Show Hidden Products is on.
* Removed: Skip First. Layouts that used it now start from the first matching product.
* Removed: The shopper sort-direction filter.
* Fixed: The social share Alignment setting showed no option selected by default.

= 1.0.0 - 01 October 2026 =
* First release.
* Grid and Carousel layouts, with Standard, Center and Ticker carousel modes.
* Product selection by limit, offset, include/exclude lists and product taxonomies, with a choice of sort order.
* Live filters for shoppers: taxonomy filters (buttons, dropdown, radio, checkbox), keyword search and sort direction.
* Sortable card content: image, title, meta fields, description, price, button and social share.
* Per-layout card styling and typography, and a site-wide colour scheme.
* Grid pagination: Load More, AJAX numbered pages, infinite scroll and ordinary page links.
* Carousel navigation, pagination, autoplay, transitions, multiple rows and accessibility messages.
* Live preview in the layout editor, including before a layout is saved.
* Settings for scripts and styles, and accessibility messages.
* Tools: sample layouts, settings backup and restore, and a system status report.
* Built-in Help screen.
* Theme-overridable templates.

== Upgrade Notice ==
= 1.3.2 =
Adds optional Skeleton Loading under Settings → Loading Effects. It is off until you switch it on, so existing layouts look and behave exactly as before.

= 1.3.1 =
Documentation update only: a clearer description, new screenshots and more FAQs. Plugin code, settings and layouts are unchanged.

= 1.3.0 =
Adds a List layout and three pre-made product card templates, with their own options, and reorganises Display Options into tabs. Existing layouts and shortcodes are unchanged.

= 1.2.0 =
Adds a ShopShelf Layout block and Elementor widgets, and fixes carousels on pages that load another copy of Swiper. Existing layouts and shortcodes are unchanged.

= 1.1.0 =
Adds Custom CSS & JS and more product filters. Catalog-hidden products are now left out by default, and the Skip First and shopper sort options are removed — check layouts that relied on them.
