Dynamic comparison API
Build custom integrations on top of dynamic comparison — a “Compare” link in your menu, a branded checkbox, a counter badge — with a small JavaScript API and web components.
Pro plan feature
The API is part of dynamic comparison, available on the Pro plan. The Dynamic compare app embed must be enabled.
Get the instance
The app embed adds a sc-dynamic-compare element at the end of the page body. All methods are available on it:
const dynamicCompare = document.querySelector('sc-dynamic-compare');
If your script is loaded in the <head> without defer, wait for the DOMContentLoaded event before querying the element.
Methods
| Method | Description |
|---|---|
openModal() | Opens the comparison dialog. Products are rendered automatically. |
closeModal() | Closes the comparison dialog. |
containsProduct(handle) | Returns true if the product is in the comparison list. |
getCount() | Returns the number of products in the comparison list. |
getHandles() | Returns the handles of the products in the comparison list. |
addProduct(handle) | Adds a product to the comparison list. |
removeProduct(handle) | Removes a product from the comparison list. |
toggleProduct(handle) | Adds the product if it isn’t in the list, removes it otherwise. |
clearProducts() | Removes all products from the list. The dialog closes automatically when the list becomes empty. |
const dynamicCompare = document.querySelector('sc-dynamic-compare');
dynamicCompare.addProduct('aurora-anc');
dynamicCompare.addProduct('nimbus-pro');
dynamicCompare.openModal();
The “Add to compare” checkboxes are disabled once 10 products are in the list. This limit isn’t enforced by addProduct(), but keep it in mind to keep comparisons readable.
The comparison list is saved in the browser’s local storage, so it persists across pages and visits — unless Clear compare list on page change is enabled.
Events
The app dispatches events on document whenever the list changes:
| Event | event.detail |
|---|---|
sc:dynamic-compare:add | { productHandle } |
sc:dynamic-compare:remove | { productHandle } |
Example: a “Compare” link with a counter
<a href="#" class="compare-link" hidden>
Compare (<span class="compare-link__count">0</span>)
</a>
<script>
document.addEventListener('DOMContentLoaded', () => {
const dynamicCompare = document.querySelector('sc-dynamic-compare');
const link = document.querySelector('.compare-link');
const count = link.querySelector('.compare-link__count');
const update = () => {
count.textContent = dynamicCompare.getCount();
link.hidden = dynamicCompare.getCount() < 2;
};
link.addEventListener('click', (event) => {
event.preventDefault();
dynamicCompare.openModal();
});
document.addEventListener('sc:dynamic-compare:add', update);
document.addEventListener('sc:dynamic-compare:remove', update);
update();
});
</script>
For analytics purposes, prefer the Shopify Pixel events, which respect customer privacy settings.
Create a custom “Add to compare” button
By default, the app injects a checkbox labelled “Add to compare” in product cards. To use your own design or position:
Disable the default button
In the theme editor, open App embeds › Dynamic compare and turn off Show add to compare.
Add the web component to your product cards
Edit the Liquid of your product card and wrap your markup in the
sc-add-to-compareelement, with theproduct-handleattribute. It must contain a checkbox with a label: the component checks it when the product is in the list and toggles the product when it changes.
With an implicit label (recommended):
<sc-add-to-compare product-handle="{{ product.handle }}">
<label>
<input type="checkbox" class="visually-hidden">
<span class="button">Add to compare</span>
</label>
</sc-add-to-compare>
Or with an explicit label (make sure the ID is unique in the page):
<sc-add-to-compare product-handle="{{ product.handle }}">
<input id="add-to-compare-{{ section.id }}-{{ product.id }}" type="checkbox" class="visually-hidden">
<label for="add-to-compare-{{ section.id }}-{{ product.id }}" class="button">Add to compare</label>
</sc-add-to-compare>
Style the checked state with the :checked pseudo-class, for example:
sc-add-to-compare input:checked + .button {
background: #14111f;
color: #fff;
}
Accessibility
Hide the checkbox visually (with a “visually hidden” class) rather than with display: none when possible: the checkbox stays reachable with the keyboard and announced by screen readers.