BuyButton.js - Shopify's JavaScript Library

Since the introduction of Multichannel Shopify, we’ve focused on supporting merchants as they explore new ways to sell beyond the online store. For developers, this means a new world of possibilities for building great ecommerce experiences around the web.

Developing these experiences used to be limited to building ecommerce themes with Liquid, but now, you have more ways to leverage Shopify as a developer than ever before.

Today, we’re proud to introduce a powerful and accessible development tool for your Shopify toolkit.

BuyButton.js — a new JavaScript library for building ecommerce into any website.

Shopify for JavaScript developers

We know JavaScript is a big deal these days. Surveys of the entire Shopify Partner and Developer community have shown that it’s one of the most widely known and adopted programming languages in our ecosystem. With the introduction of BuyButton.js, we want to help you use your knowledge to build bigger and better ecommerce experiences with Shopify.

BuyButton.js is powerful, flexible, and easy to use. With only a few lines of code, you can retrieve and display information about products and collections, create an interactive shopping cart and call to action button, and connect to Shopify’s secure checkout.

Simply include the BuyButton.js script on your website, connect to the Shopify API with an API key, and you’ll be able to use the `createComponent` method to start displaying products published to the Buy Button channel. With no configuration you can create an experience similar to the Buy Button embed, but by passing in custom options and callbacks, you can build completely custom experiences, such as:

A shopping cart that integrates with your custom event tracking library.
Dynamically generated product listings and collections.
Product listings enhanced with custom effects, animations, or plugins .

BuyButton.js is available on NPM and CDN and is easy to integrate into any website or app, with no special tooling or workflow required.

Using BuyButton.js

To use the BuyButton.js library, you will need to install the free Buy Button app on your Shopify store, and create an API key.

To start building with BuyButton.js, you’ll need to include it in your webpage. You can download it from NPM and include it as a module, or link to the CDN:

1. Creating a Shop Client

A Shop Client will allow you to connect to the Shopify API, so that you can retrieve data about your products and collections. You will need your myshopify.com domain name, API key, and application ID to create your client and begin making requests. Check out our documentation if you are unsure of where to find your API Key or application ID.

Please note: You will need to publish product/collection if you wish to interact with to the “Buy Button” channel in Shopify.

2. Initializing the Library

You can now create a UI instance, which is the main interface you will use to create components. The ShopifyBuy.UI.init method takes the client you previously configured as its argument.

3. Creating a component

Components are created through the UI instance’s createComponent method. There are four types of components you can create this way: 'product', 'collection', 'productSet', and 'cart'. The component type is the first argument to createComponent, the second argument is the configuration object.

To create a product or collection component, you will need to pass that resource’s ID to the configuration object. Learn how to find a resource ID by reading our documentation.

The only mandatory field in the configuration object is a resource identifier, which is either an ID or a handle. You will also likely want to specify a node, which is a DOM Element to which the component will be attached.

This will append an iframe containing your product listing to the node specified. It will also create two other components: a cart, and a “cart toggle”, which is a small tab on the right side of the screen, which toggles the cart open.

4. Customizing a component

To customize your component, you can create an options object in your configuration object. Each component you wish to customize — for example, product or cart — will have its own configuration, nested within the options object. For example, to customize the product and the cart in a product component, you would pass through both cart and product objects:

There are far too many customization options to list in one blog post, but you can see an overview of the options object in the documentation.

What can be built with BuyButton.js?

We’re excited to see what you can build with BuyButton.js, but to get you started we’ve put together some examples of what’s possible. The goal behind this library is that simple customizations should be easy, and that more experienced developers will be able to achieve advanced customizations.

Here are a few examples of what you can build with BuyButton.js:

1. Custom styling

Our first example is a straightforward product embed with completely custom styling. This embed would look at home on a product page or landing page, and retains none of the “widget” appearance of the default buy buttons.

The appearance of the embed is completely customized by adding CSS properties to the “styles” object, as well as overriding the default elements that appear in the embed, and changing the order of these elements.

See the Pen BuyButton.js example 5 by tessa-lt (@tessa-lt) on CodePen.

2. Custom templates

This example demonstrates a smaller button-style embed, with only a button and some pricing info. This style of embed can give you a lot of flexibility, and can be easily customized to fit any brand.

To build this embed, all elements have been removed, except for a button element, by editing the “contents” object. To add extra information to the button, including price and comparison price, the template for the button has been overridden. Templates are written using the mustache syntax, and compiled with mustache.js.

See the Pen BuyButton.js example 6 by tessa-lt (@tessa-lt) on CodePen.

You can also override templates and contents to create completely custom markup, giving you the freedom to re-arrange and position elements in your embed.

In this example, the contents of the embed have been overridden to include a new user-defined element, called “info”, which has its own template with completely custom HTML.

See the Pen BuyButton.js example 4 by tessa-lt (@tessa-lt) on CodePen.

Here’s another example of custom templates, which features several products embedded together, as well as custom elements animating on hover through CSS animations.

See the Pen BuyButton.js example 1 by tessa-lt (@tessa-lt) on CodePen.

3. Custom behavior

The following example mimics the appearance of an apparel product listing, featuring multiple options and variants with varying stock levels. This type of embed can offer a seamless experience for users looking to quickly determine if the variant they want is in stock. Rather than select options from select menus, users click on swatches and size codes.

To create this experience, the templates for the “option” component are overridden to replace the select menus with styled buttons.

The custom behavior of these buttons is controlled through the “viewData” object, which allows custom data to be attached to elements in the product embed. In this example, hex codes for each color, and short forms for each size are mapped to each option value.

See the Pen BuyButton.js example 2 by tessa-lt (@tessa-lt) on CodePen.

These are just a few examples of the flexibility afforded by BuyButton.js, which we hope will offer you a balance between customization and ease of use. The goal of BuyButton.js is to handle the more challenging aspects of integrating ecommerce on the client-side, such as state management, event and data binding, and coordination between components.

However, if you’re a more experienced JavaScript developer, and want to create a fully custom experience, you may prefer to work with the library that powers BuyButton.js, the Shopify JS Buy SDK.

Full control with the JS Buy SDK

The JS Buy SDK is a lightweight library that allows you to build ecommerce into any website. It is based on Shopify’s API and provides the ability to retrieve products and collections from your shop, add products to a cart, and checkout.

The JS Buy SDK leaves the presentation of your integration up to you; you can create whatever user interface you like, using whatever tools you like to work with. You can build a shopping cart with jQuery and CSS, or integrate the JS Buy SDK into your Single Page App, wrapping the API in React, Ember, or Angular components. The JS Buy SDK can even be used on the server, and integrated into a Node app.

The JS Buy SDK is available on NPM and CDN — to get started take a look at the documentation, or look at some examples.

Building on Shopify with JavaScript just got a whole lot easier

Regardless of your skill level or the experience you want to create, we’re committed to empowering you to build with Shopify using JavaScript. Whether you want to create a simple buy button or a complex, custom ecommerce-integrated application, we hope BuyButton.js and the JS Buy SDK will give you the tools you need to build with the Shopify platform.

To get started building ecommerce experiences with JavaScript, download BuyButton.js or the JS Buy SDK, and install the free Buy Button app on your Shopify store. We can’t wait to see what you’ll come up with.

Tessa Thornton