A Home Page Widget shows Rebuy product recommendations on your store's home page, so a shopper who lands on your site sees your best sellers, their own previously purchased items, or a hand-picked set of featured products before they start browsing. This guide takes you from an empty widget to a live one: pick a starting configuration, set up the data source, set the layout, write the copy, install the widget in your theme, and turn on Live Mode.
Choose a widget card for your home page
A Home Page Widget starts from one of the widget cards on the Create New Widget page, and picking the card is the first thing you do when creating the widget. Each card that can go on a home page creates the widget, creates a matching data source, and fills in the endpoint for you, and every card in the table below except Custom Widget also fills in the heading text. The home page cards in the table below all create the same Product Cross-Sell widget type, so whichever you pick can be reconfigured into any of the others afterward.
The table below lists common home page widget cards and what each card's data source returns.
Widget card | What its data source returns |
Tabbed Recommendations | Show more of your catalog in one spot. Shoppers switch between tabs such as Best Sellers, New Arrivals or a curated collection, each powered by its own Al or custom data source, so more products get seen and added. |
Top Sellers | Your store's best selling products, reordering itself as your sales data changes |
Buy it Again | Products the customer has bought before, with AI recommendations filling any slots left over |
Featured Items | Specific products you pick yourself, with AI recommendations filling any slots left over |
Recently Viewed | The shopper's own browsing history, tracked across devices |
Custom Widget | Nothing picked yet. It starts from the same data source as Featured Items, an empty product list with AI recommendations filling the slots, but with no heading text, so you build both yourself |
Top Sellers is the usual starting point for a home page, because it needs no configuration and works for a first-time visitor who has no history for Rebuy to personalize against. To see every widget card that can go on a home page, set the Location dropdown on the Create New Widget page to Home Page. For the full catalog of every Rebuy widget type and where each one can go, see Rebuy Widget Types.
Step 1: Create the Home Page Widget
You create a Home Page Widget from a widget card on the Widgets page, picking the widget first and choosing Home Page as its location afterwards.
In the Rebuy admin sidebar, click Cart & Merchandising and then Widgets. On some plans the sidebar shows a single Merchandising Widgets entry instead, which opens the same Widgets page.
Click Create New. If this is your store's first widget, the button reads Create Your First Widget instead.
Set the Location dropdown above the widget cards to Home Page, then find the card you want, such as Top Sellers.
Click Create on that card.
When Rebuy asks you to choose a location, select Home Page and click Continue.
The widget editor opens. Its top bar shows TYPE: Home Page • Product Cross-Sell and the WIDGET ID you need for installation in Step 5.
Rebuy creates the widget and its data source as soon as you click Continue, and there is no step to name the widget first. The goal buttons, the location picker, and the Your Widgets table are covered in Widget Dashboard Page: Create a Widget and Manage the Ones You Have.
Important: Live Mode is already on for a new widget, so it becomes visible to shoppers the moment you install it in your theme. To check your work first, toggle Live Mode off in the widget editor before you install, then follow Using Rebuy preview mode.
Step 2: Set Up the Data Source
The widget's data source decides both which products your Home Page Widget recommends and whether it appears at all. A Home Page Widget renders whenever its data source returns at least one product and hides itself when the rules return nothing, so the rules are your visibility control as well as your merchandising control.
In the widget editor sidebar, find the DATA SOURCE section.
Click Edit beside the section heading to open the connected data source in a new tab. Edit appears only when the Endpoint dropdown points at one of your own data sources, so if it is missing, pick your data source from the Custom Endpoints group in that dropdown or click Create new data source.
Set the rule's IF condition, which decides when the rule fires, and its RETURN, which decides which products it shows.
Click Save, then click Preview Ruleset to confirm the rule matches and to see the products it returns.
The starting configuration you picked in Step 1 has already written a working rule, so you only need to change anything here when you want to control what appears. For the full rule reference, see Data Sources 101. For what each built-in endpoint returns, see Data Source "Endpoints" - General Overview. To test a rule before it goes live, see Previewing Data Sources.
The home page has no product for a rule to read
The home page has no product on it, and that is the single fact that makes a Home Page Widget's data source rules different from any other widget's. Most IF conditions ask a question about the input product, which is Rebuy's name for the product a widget is reacting to. On a product page the input product is the product being viewed, and in the cart it is whatever the shopper has added. A home page has neither, so a Home Page Widget runs with no input product at all, and a condition that tests a product value has nothing to compare against.
This is why every starting configuration arrives with its condition set to IF Products with the operator Equals Anything. That operator skips the comparison and reports a match no matter what, so the rule always fires and the RETURN side does the work of choosing products. Change it to something like Product Tags set to Contains Any and the rule stops firing, so the widget shows nothing even though your tags are right and your products are right.
The IF conditions that work on a Home Page Widget are the following:
IF Anything, which always matches.
IF Products with the operator Equals Anything, which always matches.
IF URL with the operator Equals, which matches when the shopper is on the page address you enter.
The IF dropdown on a Home Page Widget's data source still lists every other condition, since Rebuy shows the same condition list on every data source. Any product-based IF condition not listed above will not match on a Home Page Widget, so a rule built on it never fires and the widget shows no products.
Filter input products is checked on the data source Rebuy created for you. It stops a widget recommending the product a shopper is already looking at, and on the home page there is no input product for it to filter, so it makes no difference either way. Leave it checked.
Cart conditions on the home page update only when the page reloads
Cart conditions such as Cart Subtotal work on a Home Page Widget, but the widget reads the cart only when the home page loads. For example, a rule reading IF Cart Subtotal is greater than $99 shows its products only after the shopper refreshes the page. For an offer that reacts to the cart right away, use a cart widget or a Smart Cart component instead.
Show signed-in customers their own set of products
To show signed-in customers different products from guests on the home page, build the data source with an IF Customer rule first and an always-true rule after it. IF Customer matches only when the shopper is signed in to a customer account, so the second rule keeps the widget showing products for guests and first-time visitors.
In Rule #1, set IF to Customer and set RETURN to what signed-in customers should see:
Endpoint set to Buy It Again, to show their previously purchased items.
Collection, Products with Tags (operator Contains), or Products, to show a specific set of products, such as a returning-customer sale.
Optionally, click + under the RETURN and add Title with a heading for signed-in customers, such as
Welcome back. This replaces the widget's title only when this rule matches.Turn on Exit If Matched for Rule #1.
Click Add After to create Rule #2, set IF to Anything, and set RETURN to the products everyone else should see.
Click Save.
Rebuy checks data source rules from the top down. With Exit If Matched on, a signed-in customer stops at Rule #1, and every other shopper falls through to Rule #2. To target a smaller group of customers by tag, see How to Target Specific Customer Segments Using Customer Tag Rules.
Step 3: Set the Layout for Each Screen Size
The Screens section of Widget Settings controls how your Home Page Widget's products are laid out on each device. It does not change how many products the widget loads, which is set by Max Number of Products displayed in the DATA SOURCE section (8 by default, up to 20).
Screens has a separate card for Large Screen (wider than 768px), Medium Screen (481px to 768px), and Small Screen (480px and narrower). Each card has its own settings, so update every screen size when you change one. Each card holds the settings in the table below.
Setting | What it does |
Display Style | How each product is drawn: Grid, List, Line, or None. Setting it to None hides the widget entirely at that screen size. |
Carousel | Turns the products into a horizontal slider with arrows instead of a block that wraps onto more rows. |
Show Paginations | Adds pagination dots below the products. It only has an effect when Carousel is also on. |
Grid Columns | How many products sit side by side, from 1 to 6. Whole numbers only. |
With Carousel on, Grid Columns is how many products show at once and the rest sit behind the arrows. With Carousel off, every product loads and wraps onto as many rows as it needs.
Step 4: Write the Widget's Copy
The Language tab holds every piece of text your Home Page Widget displays, and its title is what shoppers read as the section heading on your home page. A new widget inherits its title from the starting configuration you picked, so a widget created from Top Sellers opens with "Top Sellers" already in place.
In the widget editor, open the Language tab.
Under General, set Title to the heading shoppers should see, such as
Shop our best sellers.Set Super Title if you want a smaller line above the heading, and Description if you want a sentence below it. Either can be left empty.
Under Call to Action, adjust Add to Cart and the other button labels if your store uses different wording.
Click Save.
Step 5: Install the Widget on Your Home Page
Creating a Home Page Widget does not place it on your storefront, so the widget does nothing until it is installed on your home page template. Which method you use depends on your theme version, and the widget editor generates the code either way.
In the widget editor, click INSTALL in the top bar to open the guide for that specific widget, and copy your WIDGET ID from the same top bar.
Install using the method that matches your theme:
Online Store 2.0 themes: add a Rebuy Widget app block to your home page template and enter the widget ID. Full steps: Installing Rebuy Widgets via App Blocks in 2.0 Themes.
Vintage (1.0) themes: paste the widget's container into your home page template. Full steps: Manually Installing Widgets.
Save the theme and reload your home page.
Reposition the widget after installing it
If the widget renders in the wrong place on your home page, you can move it without editing theme code, and on a 2.0 theme the first method below is the one to reach for.
Drag the app block in Shopify's theme editor. In Shopify, go to Online Store > Themes > Customize, select your home page template, find the Rebuy Widget block in the section list, drag it to where you want the recommendations, and save. This needs no code and is the right choice whenever the block can be dragged to the spot you want.
Use Dynamic Placement in the widget editor. Reach for this when dragging cannot get you there, meaning the spot you want sits inside another section, or your theme is a vintage (1.0) theme with no app block to drag, or you want the widget in a different position on mobile than on desktop. In the widget editor, open Display tab > Dynamic Placement and set Placement Selector to a CSS selector for the element on your home page that the widget should attach to, then set Placement Location to Before, After, Prepend, or Append. For help finding a selector, see Dynamic Placement Selectors.
Note: Dynamic Placement overrides the app block's position. If a Placement Selector is set, the widget moves itself to that selector on page load and ignores where you dragged the block. If dragging the app block appears to do nothing, open Display tab > Dynamic Placement and clear any selector left over from earlier troubleshooting.
Step 6: Test the Widget, Then Turn On Live Mode
Testing before shoppers see the widget is the reason to turn Live Mode off in Step 1, and turning it back on is what makes your Home Page Widget public.
With Live Mode off, open your home page in Rebuy preview mode.
In the Rebuy preview bar at the bottom of the browser, click REBUY DATA and confirm the widget's status is READY, which means it initialized and its data source returned products.
Check the widget on a phone as well as a desktop, because the Screens settings are configured separately per device size.
Add a product from the widget and confirm it lands in the cart.
Return to the widget editor, toggle Live Mode on, and click Save.
Reload your home page as a normal shopper. The widget should now render for everyone.
If the widget still does not appear, work through the frequently asked questions below first, then see Why Isn't My Widget Showing?.
Optional: Add a Discount to the Recommendations
You can attach a discount to a Home Page Widget so its recommended products display at a reduced price. Making that discount actually apply at checkout takes one setting beyond the amount itself.
In the widget editor, open the Discount tab.
Choose a Discount Type, either Percentage or Fixed, then enter the amount.
Toggle Discounted By Functions on. This creates an automatic discount in Shopify scoped to this widget, so the discount applies when a shopper adds the product. Shopify Functions discounting is available on all Shopify plan types.
Set Discounted From to Price or Compare at Price, depending on which value the discount should calculate against.
Click Save.
If Discounted By Functions is left off, Rebuy shows the discounted price in the widget but the shopper is charged full price at checkout, because the widget's discount is display only in that mode. You would then need to create a matching discount in Shopify yourself. For the full picture, see the Rebuy Discounting Overview.
Widget Editor Settings That Matter for a Home Page Widget
The widget editor shows the same tabs for every widget type, and most of them behave the same wherever the widget sits. The settings below are the ones that change how a Home Page Widget behaves on a full-width page with no product on it.
Setting | Where it is | What it does here |
Live Mode | Widget editor left panel | On for a new widget, so the widget is public as soon as it is installed. Off renders it only in Rebuy preview mode. |
Max Number of Products displayed | DATA SOURCE section | How many recommendations the widget requests, starting at 8 with a maximum of 20. |
Screens | Widget Settings > Screens | Display Style, Carousel, Show Paginations, and Grid Columns, set separately per device size. A home page has more width to work with than a cart drawer, so this is usually where a Home Page Widget gets adjusted first. See Step 3. |
Display Type | Widget Settings > General | Embed renders the widget inline in the page, which is what a Home Page Widget needs. Popup keeps it hidden until a trigger fires, and a home page has no add-to-cart action to trigger it from. |
Enable Variant Selector | Widget Settings > Variant Selector | Shows variant options on the recommended products, and is on unless you turn it off. Variant Selector Type switches between a Select dropdown and swatch-style Buttons; Buttons requires Shopify options named "Color", "Colour", or "Size". |
Add to Cart Redirect | Widget Settings > View Options | Where the shopper goes after adding from the widget: None (Stay on Current Page), Redirect to Cart, Redirect to Checkout, Close modal, or Create Draft Order. Staying on the page keeps a home page shopper browsing. |
Limit Views | Widget Settings > View Options | Caps how often one shopper sees the widget, paired with Max View Count and Every in days. A widget suppressed this way shows status HIDDEN in Rebuy preview mode. |
Enable Timer | Widget Settings > Timer | Adds a countdown inside the widget, with Timer Title, Minutes, and Seconds setting the text and duration. Action decides what happens at zero: Dismiss Widget removes the widget, Redirect to Cart and Redirect to Checkout navigate the shopper away, and Stop Timer leaves the widget in place at zero. |
Enable Quick View | Product settings > Quick View Options | Lets shoppers open a product's details in a modal from inside the widget without leaving the home page. |
Theme and CSS | Display tab | Theme switches between Rebuy's standard styling and Custom, which reveals color pickers plus Button Border Width and Button Radius. The CSS box handles anything those fields cannot reach, including all spacing and typography. |
Enable Attribution Tracking | Advanced > Product Properties | Tags items added from this widget so they appear in Rebuy reporting. It is on already and should stay on. |
Placement Selector | Display tab > Dynamic Placement | Moves the widget to a CSS selector on page load, overriding wherever you dragged the app block. See Step 5. |
Limitations
The following constraints apply to Home Page Widgets. Each has a workaround or an alternative where one exists.
A Home Page Widget has no input product, so product-level IF conditions match only with Equals Anything. Filter on the RETURN side instead, as described in Step 2. There is no setting that gives a home page an input product.
Smart Sort and Similar Sort have nothing to sort against on the home page. Use RETURN Collection with a Trending sort, or the Top Sellers endpoint, each of which reads your store's sales data rather than the page.
The Similar Products (AI) endpoint cannot be used on a Home Page Widget because it requires a product ID. Use Recommended (AI) or Trending Products (AI) for AI-driven recommendations without one.
The widget hides itself when its data source returns no products. This is intended behavior. If a correctly installed Home Page Widget never appears, check the data source rules first using Previewing Data Sources.
A widget ID renders once per page. If the same widget ID appears twice on your home page, in two app blocks or in an app block plus a manual container, Rebuy keeps the first placement in the page's document order and removes the rest from the page entirely. The removal is silent and the removed placement is not listed in Preview Mode. Duplicate the widget from its row on the Widgets page and point the second placement at the duplicate's ID.
Grid Columns accepts whole numbers only. A half-item peek hinting at more products to scroll takes custom CSS and is not a setting.
Custom templates are theme code, not an editor setting. A Home Page Widget renders with Rebuy's recommended template, and the widget editor has no field to change it. A developer overrides it by adding a template script tag to the theme, using the ID
rebuy-widget-[WIDGET ID]to override that one widget orrebuy-recommended-templateto override every widget on the page that uses the recommended template. See Widget Custom Templates. While a custom template is active, the editor's preview no longer matches what shoppers see.The widget does not remove products or discounts. It adds to the cart and its involvement ends there, so a product a shopper added from the widget stays in the cart even if they later change the cart so the rules no longer match.
Style the Widget to Match Your Store
The widget editor's Display tab is where a Home Page Widget's appearance is set, and one of the paths it offers needs no code at all.
Set Theme to "Custom" for colors and button shape. Open the Display tab and you will see a Theme dropdown selector with no styling fields under it. Switch Theme to Custom and the tab reveals color pickers for the widget's frame, its Add to Cart buttons, the carousel arrows and dots, its own title and description text, each product's title, description and vendor, prices, review stars, and the variant selector, plus number fields for button geometry, Button Border Width and Button Radius. A button border shows only while Button Border Width is above 0.
Use the CSS box for everything else. The CSS box sits in the same tab and stays available whether Theme is Custom or not. Reach for it when the fields above cannot get you there, which in practice means spacing, font sizes and font families, hover states, and hiding an element. There are no spacing or typography fields in the Custom theme, so any type or layout change is a CSS change.
Note: CSS from this box is not scoped to the widget for you. Always scope your selectors to the widget ID, as in #rebuy-widget-12345 .primary-title, or your styling will reach other Rebuy widgets on the same page.
For ready-made snippets aimed at this widget's layout, see the Product Page Recommendation Widget CSS Styling Guide, which applies to a Home Page Widget too, since it is the same Product Cross-Sell widget type. Custom CSS falls outside standard Rebuy support, and Rebuy's Partner team can connect you with an agency if you do not have a developer.
For ideas on what to put on your home page and where, see Home Page Best Practices.
Frequently Asked Questions
Does it matter that my widget is on the home page when I build a data source rule?
Yes, the page your widget sits on decides whether a rule can fire at all. IF conditions in the Product Rules group, such as Product Tags and Product Type, read the product on the page, and a home page does not have one, so on a Home Page Widget any operator other than Equals Anything never matches. The same rule works on a product page, where the product being viewed is the input product. On a Home Page Widget, keep the condition on Products with Equals Anything and choose your products on the RETURN side instead.
How do I show my best selling products with a specific tag on the home page?
Showing best sellers filtered by tag on the home page takes a Shopify collection, because the tag filter and the sales ordering live on different RETURN options. Create an automated collection in Shopify whose condition is your product tag, then in your Home Page Widget's data source leave the IF condition on Products with Equals Anything, set RETURN to Collection, pick that collection, and set SORT BY to Trending (90 days), which reads your store's sales data over that window and needs no input product.
How do I show only products with a specific tag on my Home Page Widget?
To show only products with a specific tag on a Home Page Widget, leave the IF condition on Products with Equals Anything and filter on the RETURN side. Set RETURN to Products with Tags, change the operator to Contains, and type your tags exactly as they appear in Shopify, separated by commas. A product must carry every tag you list. Leave the operator on its default of Contains ALL Matched Input Tags and the widget shows nothing, since that option matches tags against a product on the page and a home page has none. Click Save, then Preview Ruleset to confirm the products it returns.
How do I sort my Home Page Widget's products by best sellers?
To sort a Home Page Widget's products by best sellers, set RETURN to Endpoint and pick Top Sellers, since Smart Sort and Similar Sort need a product on the page and are skipped on the home page. Top Sellers reads your store's sales data and needs no product on the page.
Which RETURN options and endpoints don't work on a Home Page Widget?
The RETURN options that don't work on a Home Page Widget are the ones that read a product on the page, since a home page has none and they come back empty. These are Input Products, Products with Tags set to Contains ALL Matched Input Tags or Contains ANY Matched Input Tags, and Endpoint set to Similar Products (AI).
Every other endpoint works on a Home Page Widget, including Recommended (AI), Top Sellers, and Trending Products (AI). Buy It Again, Recently Viewed, and Complementary to Items You've Viewed also work, since they read the shopper's own history rather than the page.
Why is my Home Page Widget showing no products?
A Home Page Widget most often shows no products because its data source rule uses a condition that needs a product on the page. Work through these in order:
The IF condition. Open the data source and check it first. Anything in the Product Rules group with an operator other than Equals Anything never matches on a home page.
The RETURN side. Products with Tags set to either matched-input-tags option comes back empty for the same reason, and so does Input Products and the Similar Products (AI) endpoint.
Preview Ruleset. Use it in the data source editor to confirm whether the rule matches before you investigate tags, product status, or the cache.
Live Mode. A widget with Live Mode off renders only in Rebuy preview mode, not for shoppers.
Installation. Confirm the app block is on your home page template, or that the container is in the theme file. In Rebuy preview mode, a widget that is not installed on the page you are viewing does not appear in the REBUY DATA panel at all.
Display Style set to None. In the widget editor under Widget Settings tab > Screens, a Display Style of None hides the widget at that screen size. A widget that shows on desktop but never on mobile is very often set to None on Small Screen.
Limit Views. If Limit Views is on and the shopper has already reached Max View Count, the widget stays hidden until the window in Every expires. Its status reads HIDDEN in the REBUY DATA panel.
For broader troubleshooting, see Why Isn't My Widget Showing?.