Combined Listings in Hydrogen
This recipe lets you more precisely display and manage combined listings on product pages and in search results for your Hydrogen storefront. A combined listing groups separate products together into a single product listing using a shared option like color or size. Each product appears as a variant but can have its own title, description, URL, and images. In this recipe, you'll make the following changes:
- Set up the Combined Listings app in your Shopify admin and group relevant products together as combined listings.
- Configure how combined listings will be handled on your storefront.
- Update the
ProductFormcomponent to hide the Add to cart button for the parent products of combined listings. - Update the
ProductImagecomponent to support images from product variants and the product itself. - Show a range of prices for combined listings in
ProductItem.
Note
This recipe is compatible with React Router 7.9.x and uses consolidated imports from 'react-router' instead of separate '@shopify/remix-oxygen' and '@remix-run/react' packages.
Note:
This recipe is compatible with React Router 7.9.x and uses consolidated imports from 'react-router' instead of separate '@shopify/remix-oxygen' and '@remix-run/react' packages.
Anchor to RequirementsRequirements
- Your store must be on either a Shopify Plus or enterprise plan.
- Your store must have the Combined Listings app installed.
Anchor to IngredientsIngredients
New files added to the template by this recipe.
| File | Description |
|---|---|
| app/lib/combined-listings.ts | The combined-listings.ts file contains utilities and settings for handling combined listings. |
Anchor to Step 1: Set up the Combined Listings appStep 1: Set up the Combined Listings app
-
Install the Combined Listings app.
-
Add tags to the parent products of combined listings to indicate that they're part of a combined listing (for example
combined).
Anchor to Step 2: Configure combined listings behaviorStep 2: Configure combined listings behavior
You can customize how the parent products of combined listings are retrieved and displayed.
To make this process easier, we included a configuration object in the combined-listings.ts file that you can edit to customize according to your preferences.
// Edit these values to customize the combined listings behaviors
export const combinedListingsSettings = {
// If true, loading the product page will redirect to the first variant
redirectToFirstVariant: false,
// The tag that indicates a combined listing
combinedListingTag: 'combined',
// If true, combined listings will not be shown in the product list
hideCombinedListingsFromProductList: true,
};
Anchor to Step 3: Add combined listings utilitiesStep 3: Add combined listings utilities
Create a new combined-listings.ts file that contains utilities and settings for handling combined listings.
File
// Edit these values to customize combined listings' behavior
export const combinedListingsSettings = {
// If true, loading the product page will redirect to the first variant
redirectToFirstVariant: false,
// The tag that indicates a combined listing
combinedListingTag: 'combined',
// If true, combined listings will not be shown in the product list
hideCombinedListingsFromProductList: true,
};
export const maybeFilterOutCombinedListingsQuery =
combinedListingsSettings.hideCombinedListingsFromProductList
? `NOT tag:${combinedListingsSettings.combinedListingTag}`
: '';
interface ProductWithTags {
tags: string[];
}
function isProductWithTags(u: unknown): u is ProductWithTags {
const maybe = u as ProductWithTags;
return (
u != null &&
typeof u === 'object' &&
'tags' in maybe &&
Array.isArray(maybe.tags)
);
}
export function isCombinedListing(product: unknown) {
return (
isProductWithTags(product) &&
product.tags.includes(combinedListingsSettings.combinedListingTag)
);
}
- Update the
ProductFormcomponent to hide the Add to cart button for the parent products of combined listings and for variants' selected state. - Update the
Linkcomponent to not replace the current URL when the product is a combined listing parent product.
File
export function ProductForm({
productOptions,
selectedVariant,
+ combinedListing,
}: {
productOptions: MappedProductOptions[];
selectedVariant: ProductFragment['selectedOrFirstAvailableVariant'];
+ combinedListing: boolean;
}) {
const navigate = useNavigate();
const {open} = useAside();
key={option.name + name}
prefetch="intent"
preventScrollReset
- replace
+ replace={!combinedListing}
to={`/products/${handle}?${variantUriQuery}`}
style={{
- border: selected
- ? '1px solid black'
- : '1px solid transparent',
+ border:
+ selected && !combinedListing
+ ? '1px solid black'
+ : '1px solid transparent',
opacity: available ? 1 : 0.3,
}}
>
}`}
key={option.name + name}
style={{
- border: selected
- ? '1px solid black'
- : '1px solid transparent',
+ border:
+ selected && !combinedListing
+ ? '1px solid black'
+ : '1px solid transparent',
opacity: available ? 1 : 0.3,
}}
disabled={!exists}
</div>
);
})}
- <AddToCartButton
- disabled={!selectedVariant || !selectedVariant.availableForSale}
- onClick={() => {
- open('cart');
- }}
- lines={
- selectedVariant
- ? [
- {
- merchandiseId: selectedVariant.id,
- quantity: 1,
- selectedVariant,
- },
- ]
- : []
- }
- >
- {selectedVariant?.availableForSale ? 'Add to cart' : 'Sold out'}
- </AddToCartButton>
+ {!combinedListing && (
+ <AddToCartButton
+ disabled={!selectedVariant || !selectedVariant.availableForSale}
+ onClick={() => {
+ open('cart');
+ }}
+ lines={
+ selectedVariant
+ ? [
+ {
+ merchandiseId: selectedVariant.id,
+ quantity: 1,
+ selectedVariant,
+ },
+ ]
+ : []
+ }
+ >
+ {selectedVariant?.availableForSale ? 'Add to cart' : 'Sold out'}
+ </AddToCartButton>
+ )}
</div>
);
}
Anchor to Step 5: Support product and variant imagesStep 5: Support product and variant images
Update the ProductImage component to support images from both product variants and the product itself.
-import type {ProductVariantFragment} from 'storefrontapi.generated';
+import type {
+ ProductVariantFragment,
+ ProductFragment,
+} from 'storefrontapi.generated';
import {Image} from '@shopify/hydrogen';
export function ProductImage({
image,
}: {
- image: ProductVariantFragment['image'];
+ image: ProductVariantFragment['image'] | ProductFragment['featuredImage'];
}) {
if (!image) {
return <div className="product-image" />;
Anchor to Step 6: Show a range of prices for combined listings in ProductItemStep 6: Show a range of prices for combined listings in Product
Update ProductItem.tsx to show a range of prices for the combined listing parent product instead of the variant price.
RecommendedProductFragment,
} from 'storefrontapi.generated';
import {useVariantUrl} from '~/lib/variants';
+import {isCombinedListing} from '../lib/combined-listings';
export function ProductItem({
product,
/>
)}
<h4>{product.title}</h4>
- <small>
- <Money data={product.priceRange.minVariantPrice} />
- </small>
+ {isCombinedListing(product) ? (
+ <small className="combined-listing-price">
+ <Money data={product.priceRange.minVariantPrice} />
+ <span>–</span>
+ <Money data={product.priceRange.maxVariantPrice} />
+ </small>
+ ) : (
+ <small>
+ <Money data={product.priceRange.minVariantPrice} />
+ </small>
+ )}
</Link>
);
}
Anchor to Step 7: (Optional) Redirect to the first variantStep 7: (Optional) Redirect to the first variant
If you want to redirect automatically to the first variant of a combined listing when the parent handle is selected, add a redirect utility that's called whenever the parent handle is requested.
import {redirect} from 'react-router';
+import type {ProductFragment} from 'storefrontapi.generated';
+import {isCombinedListing} from './combined-listings';
export function redirectIfHandleIsLocalized(
request: Request,
throw redirect(url.toString());
}
}
+
+export function redirectIfCombinedListing(
+ request: Request,
+ product: ProductFragment,
+) {
+ const url = new URL(request.url);
+ let shouldRedirect = false;
+
+ if (isCombinedListing(product)) {
+ url.pathname = url.pathname.replace(
+ product.handle,
+ product.selectedOrFirstAvailableVariant?.product.handle ?? '',
+ );
+ shouldRedirect = true;
+ }
+
+ if (shouldRedirect) {
+ throw redirect(url.toString());
+ }
+}
Anchor to Step 8: Filter combined listings from the all products pageStep 8: Filter combined listings from the all products page
Add filtering to the all products catalog page to exclude combined listing parent products.
import type {Route} from './+types/collections.all';
-import {
- useLoaderData,
-} from 'react-router';
+import {useLoaderData} from 'react-router';
import {getPaginationVariables, Image, Money} from '@shopify/hydrogen';
import {PaginatedResourceSection} from '~/components/PaginatedResourceSection';
import {ProductItem} from '~/components/ProductItem';
import type {CollectionItemFragment} from 'storefrontapi.generated';
+import {
+ combinedListingsSettings,
+ maybeFilterOutCombinedListingsQuery,
+} from '../lib/combined-listings';
export const meta: Route.MetaFunction = () => {
return [{title: `Hydrogen | Products`}];
const [{products}] = await Promise.all([
storefront.query(CATALOG_QUERY, {
- variables: {...paginationVariables},
+ variables: {
+ ...paginationVariables,
+ query: combinedListingsSettings.hideCombinedListingsFromProductList
+ ? maybeFilterOutCombinedListingsQuery
+ : '',
+ },
}),
// Add other queries here, so that they are loaded in parallel
]);
id
handle
title
+ tags
featuredImage {
id
altText
$last: Int
$startCursor: String
$endCursor: String
+ $query: String
) @inContext(country: $country, language: $language) {
- products(first: $first, last: $last, before: $startCursor, after: $endCursor) {
+ products(first: $first, last: $last, before: $startCursor, after: $endCursor, query: $query) {
nodes {
...CollectionItem
}
Anchor to Step 9: Filter recommended productsStep 9: Filter recommended products
- Add the
tagsproperty to the items returned by the product query. - (Optional) Add the filtering query to the product query to exclude combined listings.
File
RecommendedProductsQuery,
} from 'storefrontapi.generated';
import {ProductItem} from '~/components/ProductItem';
+import {maybeFilterOutCombinedListingsQuery} from '~/lib/combined-listings';
export const meta: Route.MetaFunction = () => {
return [{title: 'Hydrogen | Home'}];
*/
function loadDeferredData({context}: Route.LoaderArgs) {
const recommendedProducts = context.storefront
- .query(RECOMMENDED_PRODUCTS_QUERY)
+ .query(RECOMMENDED_PRODUCTS_QUERY, {
+ variables: {
+ query: maybeFilterOutCombinedListingsQuery,
+ },
+ })
.catch((error: Error) => {
// Log query errors, but don't throw them so the page can still render
console.error(error);
<Await resolve={products}>
{(response) => (
<div className="recommended-products-grid">
- {response
- ? response.products.nodes.map((product) => (
- <ProductItem key={product.id} product={product} />
- ))
- : null}
+ {response?.products.nodes.map((product) => (
+ <ProductItem key={product.id} product={product} />
+ ))}
</div>
)}
</Await>
amount
currencyCode
}
+ maxVariantPrice {
+ amount
+ currencyCode
+ }
}
+ tags
featuredImage {
id
url
height
}
}
- query RecommendedProducts ($country: CountryCode, $language: LanguageCode)
+ query RecommendedProducts ($country: CountryCode, $language: LanguageCode, $query: String)
@inContext(country: $country, language: $language) {
- products(first: 4, sortKey: UPDATED_AT, reverse: true) {
+ products(first: 4, sortKey: UPDATED_AT, reverse: true, query: $query) {
nodes {
...RecommendedProduct
}
Anchor to Step 10: (Optional) Filter out combined listings from collections pagesStep 10: (Optional) Filter out combined listings from collections pages
Since it's not possible to directly apply query filters when retrieving collection products, you can manually filter out combined listings after they're retrieved based on their tags.
File
import {redirectIfHandleIsLocalized} from '~/lib/redirect';
import {ProductItem} from '~/components/ProductItem';
import type {ProductItemFragment} from 'storefrontapi.generated';
+import {
+ combinedListingsSettings,
+ isCombinedListing,
+} from '~/lib/combined-listings';
export const meta: Route.MetaFunction = ({data}) => {
return [{title: `Hydrogen | ${data?.collection.title ?? ''} Collection`}];
export default function Collection() {
const {collection} = useLoaderData<typeof loader>();
+ // Manually filter out combined listings from the collection products, because filtering
+ // would not work here.
+ const filteredCollectionProducts = {
+ ...collection.products,
+ nodes: collection.products.nodes.filter(
+ (product) =>
+ !(
+ combinedListingsSettings.hideCombinedListingsFromProductList &&
+ isCombinedListing(product)
+ ),
+ ),
+ };
+
return (
<div className="collection">
<h1>{collection.title}</h1>
<p className="collection-description">{collection.description}</p>
<PaginatedResourceSection<ProductItemFragment>
- connection={collection.products}
+ connection={filteredCollectionProducts}
resourcesClassName="products-grid"
>
{({node: product, index}) => (
id
handle
title
+ tags
featuredImage {
id
altText
first: $first,
last: $last,
before: $startCursor,
- after: $endCursor
+ after: $endCursor,
) {
nodes {
...ProductItem
Anchor to Step 11: Show price ranges on product pagesStep 11: Show price ranges on product pages
- Display a range of prices for combined listings instead of the variant price.
- Show the featured image of the combined listing parent product instead of the variant image.
- (Optional) Redirect to the first variant of a combined listing when the handle is requested.
File
import {ProductPrice} from '~/components/ProductPrice';
import {ProductImage} from '~/components/ProductImage';
import {ProductForm} from '~/components/ProductForm';
-import {redirectIfHandleIsLocalized} from '~/lib/redirect';
+import {
+ redirectIfCombinedListing,
+ redirectIfHandleIsLocalized,
+} from '~/lib/redirect';
+import {
+ isCombinedListing,
+ combinedListingsSettings,
+} from '../lib/combined-listings';
export const meta: Route.MetaFunction = ({data}) => {
return [
// The API handle might be localized, so redirect to the localized handle
redirectIfHandleIsLocalized(request, {handle, data: product});
+ if (combinedListingsSettings.redirectToFirstVariant) {
+ redirectIfCombinedListing(request, product);
+ }
+
return {
product,
};
export default function Product() {
const {product} = useLoaderData<typeof loader>();
+ const combinedListing = isCombinedListing(product);
// Optimistically selects a variant with given available variant information
const selectedVariant = useOptimisticVariant(
// Sets the search param to the selected variant without navigation
// only when no search params are set in the url
- useSelectedOptionInUrlParam(selectedVariant.selectedOptions);
+ useSelectedOptionInUrlParam(
+ combinedListing ? [] : selectedVariant.selectedOptions,
+ );
// Get the product options array
const productOptions = getProductOptions({
selectedOrFirstAvailableVariant: selectedVariant,
});
- const {title, descriptionHtml} = product;
+ const {descriptionHtml, title} = product;
+
+ const productImage = combinedListing
+ ? (product.featuredImage ?? selectedVariant?.image)
+ : selectedVariant?.image;
return (
<div className="product">
- <ProductImage image={selectedVariant?.image} />
+ <ProductImage image={productImage} />
<div className="product-main">
<h1>{title}</h1>
- <ProductPrice
- price={selectedVariant?.price}
- compareAtPrice={selectedVariant?.compareAtPrice}
- />
+ {combinedListing ? (
+ <div>
+ <div style={{display: 'flex', gap: '10px'}}>
+ <span style={{display: 'flex', gap: '5px'}}>
+ From
+ <ProductPrice price={product.priceRange.minVariantPrice} />
+ </span>
+ <span style={{display: 'flex', gap: '5px'}}>
+ To
+ <ProductPrice price={product.priceRange.maxVariantPrice} />
+ </span>
+ </div>
+ </div>
+ ) : (
+ <ProductPrice
+ price={selectedVariant?.price}
+ compareAtPrice={selectedVariant?.compareAtPrice}
+ />
+ )}
<br />
<ProductForm
+ combinedListing={combinedListing}
productOptions={productOptions}
- selectedVariant={selectedVariant}
+ selectedVariant={combinedListing ? undefined : selectedVariant}
/>
<br />
<br />
description
encodedVariantExistence
encodedVariantAvailability
+ tags
+ featuredImage {
+ id
+ url
+ altText
+ }
+ priceRange {
+ minVariantPrice {
+ amount
+ currencyCode
+ }
+ maxVariantPrice {
+ amount
+ currencyCode
+ }
+ }
options {
name
optionValues {
Anchor to Step 12: Style the price range displayStep 12: Style the price range display
Add a class to the product item to show a range of prices for combined listings.
width: 100%;
}
+.product-item .combined-listing-price {
+ display: flex;
+ grid-gap: 0.5rem;
+}
+
/*
* --------------------------------------------------
* routes/products.$handle.tsx
Anchor to Next stepsNext steps
- Test your implementation by going to your store and searching for a combined listing. Make sure that the combined listing's details appear in the search results and on the product page.
- (Optional) Place a test order to see how orders for combined listings appear in your Shopify admin.
Was this page helpful?