API ReferenceTheme Engine ReferenceJavaScript SDK ReferenceRecharge Help CenterContact Us

Advanced widget commands for Recharge's JavaScript subscription widget

You can access additional advanced widget functionality like creating a widget on any page. This is done by accessing the widget's built-in functions. This article will outline every available method and use-cases for each method when using the JS subscription widget.

Suggest Edits

Before you start

  • To use the JS widget out of the box, your store must be using a Shopify 1.0 theme. Recharge will not be supporting customizations to the JS widget to work with 2.0 themes.
    • You can build your own custom JS widget that works on any page and with both Shopify's 1.0 and 2.0 themes. Building a custom widget allows you to make more in-depth customizations.
  • If you want to use a 2.0 theme out of box, consider using the Shopify 2.0 subscription widget. With the Shopify 2.0 Widget, place the subscription widget on your product page directly through the Online Store editor in Shopify. With this widget, you can make basic customizations directly on the Shopify Theme Editor.
    • The Shopify 2.0 subscription widget is less customizable due to it using an app-block and not requiring code.

Creating widgets with various configurations

Access advanced JavaScript methods via the browser by invoking ReChargeWidget. You can access this namespace through client-side code, or in the browser console. The following code demonstrates how you can create widgets with different configurations. 

const config = {
  productId: 123, // Required
  injectionParent: 'form[action*="cart/add"]', // The node that will have the widget injected in
  injectionMethod: 'prepend', // How will the widget be injected 
  injectFn: (node, target) => {}, // Runs a custom injection function 
  selectors: {
    price: ['.my-price-selector'], // the selectors that will be updated based on subscription
    variant: ['.variant-selector'] // The variants to watch for to update the subscription prices
  }
};
window.ReChargeWidget.createWidget(config);

// Example of rendering a specific product to a page that doesn't provide the productId in the DOM
window.ReChargeWidget.createWidget({ productId: 123 });

// Example of rendering a specific product to a page that has a custom injection point
window.ReChargeWidget.createWidget({ productId: 123, injectionParent: '.rc-custom-injection-point' });

// Example of rendering a specific product to a page that has a special price selector
window.ReChargeWidget.createWidget({ productId: 123, selectors: { price: ['.my-price'] } });

Widget methods

The following table outlines widget methods and example code:

MethodDescriptionExample
createWidget(config)Creates and returns a new widget instance.window.ReChargeWidget.createWidget([{ productId: 123 }]);
createWidgets(configs)Creates multiple widgets. Returns an array.window.ReChargeWidget.createWidget([{ productId: 123 }, { productId: 12456 }]);
getWidgetsReturns all instances of widgets.window.ReChargeWidget.getWidgets();
getWidgetByProductIdReturns a single widget by product ID.window.ReChargeWidget.getWidgetByProductId(123);
destroyWidgetsDestroys all widgets.window.ReChargeWidget.destroyWidgets();
currentVariantIdReturns the current variant ID used.window.ReChargeWidget.currentVariantId;
enablePreviewModeAllows you to preview the widget mimicking a live widget and will show whether a widget is published or not.window.ReChargeWidget.enablePreviewMode();
useVariantIdElementAllows the JS widget to map variant selector elements when it doesn’t work out of the box.window.ReChargeWidget.useVariantIdElement;

Additionally, you can listen to events such ReChargeWidget-loaded and widget:build to wait for the ReChargeWidget object to be ready.

API

The following reference outlines client-side calls you can make to the Recharge API for returning information about the widget and product.

// Fetch an individual product
window.ReChargeWidget.api.fetchProduct(id);
// Fetches the store settings
window.ReChargeWidget.api.fetchStoreSettings();
// Fetches the widget settings
window.ReChargeWidget.api.fetchWidgetSettings();
// Fetches all widget data. This includes store settings, widget settings, and products
window.ReChargeWidget.api.fetchWidgetData();
// Fetches all products
window.ReChargeWidget.api.fetchProducts();
// Gets the cart
window.ReChargeWidget.api.getCart();
// Posts items to cart
window.ReChargeWidget.api.postToCart({ id, sellingPlanId, sellingPlanGroupId, isSubscription });

Updated 3 months ago

Need Help? Contact Us