ShopifyCheckoutJS

A little library that will help you manipulate Shopify´s Checkout via JS.

IMPORTANT: Shopify Plus is needed. The resulting JS needs to be included in checkout.liquid file which is only available to Shopify Plus stores.

• Other versions
• 1. Install
• 2. $checkout object
  • 2.1. Events
• 3. Components
  • 3.1. General component methods
  • 3.2. Sections
  • 3.3. Radio buttons group
• 4. Fields
  • 4.1. General field methods
  • 4.2. TextFields
  • 4.3. Checkboxs
  • 4.4. Dropdowns
• 5. Shipping methods
  • 5.1. Add description to shipping method
  • 5.2. Get/set checked status
  • 5.3. Get shipping info
• 6. Payment methods
  • 6.1. Add description to payment method
  • 6.2. Get/set checked status
  • 6.3. Get payment method info

Other versions

Please refer to each version branch in case you are using a previous verions.

Important: V0.2.0 has breaking changes.

v0.1.0: https://github.com/adearriba/ShopifyCheckoutJS/tree/v0.1.0

1. Install

npm i @adearriba/shopify-checkout

2. $checkout object

The $checkout object is created to help with the different tasks manipulating Shopify´s checkout page.

2.1. Events

To register handlers for common events, you can use the $checkout.on(event, callback) function.

import { $checkout } from '@adearriba/shopify-checkout/checkout.js';

$checkout.on('load', (e) => { console.log(e); })

$checkout.on('load:information', function(e) { 
    console.log(e); 
})

$checkout.on('error', function(e) { 
    console.trace(); 
})

Loading events

This are events related to loading or changing a page/step during the checkout process: |Event name|Descripcion| |---|---| |continue|Triggers whenever any of any checkout pages are submitted.| |load|This is triggered for convenience in every Shopify´s page:load or page:change event.| |load:information|Information step is loaded| |load:shipping|Shipping step is loaded. The event.detail object contains the shipping methods shown in the page.| |load:payment|Payment step is loaded. The event.detail object contains the payment methods shown in the page.| |load:processing|Processing page is loaded| |load:thankyou|Thank you page is loaded| |load:orderstatus|Order status page is loaded| |load:stockproblems|Stock problems page is loaded. The event.detail object contains a list of name and variant of the products shown in the page.|

Interactive events

This are events related to interactions with the UI.

Event name	Descripcion
shippingmethod:changed	When a shipping method is selected. The event.detail contains the shipping method object.
paymentmethod:changed	When a payment method is selected. The event.detail contains the payment method object.
component:changed	When a component's value changes. The event.detail contains the component that changed.
field:changed	When a field's value changes. The event.detail contains the field that changed. Not all Fields are components so this is a special type of InputComponent.

Other events

Event name	Descripcion
error	When an exception is catch inside a callback of any triggered event
field:created	When a field is created. The field reference is inside the event.detail property.
field:removed	When a field is removed. The field reference is inside the event.detail property.

3. Components

3.1. General component methods

Insert components into the DOM

Components can be inserted before or after another components. Here an example with fields, which are a specific type of component. Below you'll find an example for sections.

$checkout.fields["checkout_billing_address_phone"].insertBefore(field);
$checkout.fields["checkout_billing_address_last_name"].insertAfter(field);

Watch for changes in components

When a component changes, the checkout:component:changed event triggers. Note: In case of fields, a checkout:field:changed event triggers. For a shorthand, instead of remembering the name of the event, you can use onValueChanged(callback) for both components and fields. At the same time, you can also use on('changed', callback).

field.onValueChanged(function(event){
    console.log(event);
});

field.on('changed', function(event){
    console.log(event);
});

component.onValueChanged(function(event){
    console.log(event);
});

component.on('changed', function(event){
    console.log(event);
});

3.2. Sections

In Shopify's checkout, you'll encounter different sections within a page. In case you want to create a new section for an additional form or separate controllers, you can do so.

Get a section that already exists

//always import the corresponding component
import {SectionComponent} from '@adearriba/shopify-checkout/checkout';

//Using a css selector, you can create a reference to an existing section
let shippingFormSection = new SectionComponent({selector: '.section--shipping-address'});

Create a new section and add it before/after another one

import {SectionComponent} from '@adearriba/shopify-checkout/checkout';

//Create a new Section component
let section = new SectionComponent({name: 'shipping-method', title: 'Shipping method'});

//Add the section before or after the previous reference
shippingFormSection.insertBefore(section);
shippingFormSection.insertAfter(section);

3.3. Radio buttons group

Create a radiobox in a section

//Import both components together
import {SectionComponent, RadioContentBoxComponent} from '@adearriba/shopify-checkout/checkout';

//Create a new RadioContentBoxComponent
var radioBox = new RadioContentBoxComponent({name: 'RadioContentBox' });

//Create an option using innerHTML instead of a text label
let option1 = {
    htmlFor: 'shipping', 
    value: 'shipping', 
    innerHTML: '<svg aria-hidden="true" class="icon-svg icon-svg--size-18 icon-svg--inline-before" focusable="false" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><path d="M17.816 14c-.415-1.162-1.514-2-2.816-2-1.302 0-2.4.838-2.816 2H12v-4h6v4h-.184zM15 16c-.55 0-1-.45-1-1s.45-1 1-1 1 .45 1 1-.45 1-1 1zM5 16c-.55 0-1-.45-1-1s.45-1 1-1 1 .45 1 1-.45 1-1 1zM2 4h8v10H7.816C7.4 12.838 6.302 12 5 12c-1.302 0-2.4.838-2.816 2H2V4zm13.434 1l1.8 3H12V5h3.434zm4.424 3.485l-3-5C16.678 3.185 16.35 3 16 3h-4c0-.552-.448-1-1-1H1c-.552 0-1 .448-1 1v12c0 .552.448 1 1 1h1.185C2.6 17.162 3.698 18 5 18s2.4-.838 2.816-2h4.37c.413 1.162 1.512 2 2.814 2s2.4-.838 2.816-2H19c.552 0 1-.448 1-1V9c0-.18-.05-.36-.142-.515z" fill-rule="evenodd"></path></svg>Shipping'};

//Using a text label
let option2 = {label: 'Pickup in Store', htmlFor: 'pickup', value: 'pickup'};

//Add options to RadioContentBoxComponent
radioBox.addOption(option1);
radioBox.addOption(option2);

//Add the RadioContentBoxComponent to the previous section
section.addContent(radioBox);

//Insert the new section before the existing shippingFormSection
shippingFormSection.insertBefore(section);

Result

Get selected value

console.log(radioBox.value);

4. Fields

Fields are a special kind of components with additional functionality. Different types of fields can be created. Whenever a field is created with its constructor, it is added to the $checkout.fields dictionary with its key being 'checkout_attributes_' + ${name}.

For Shopify´s original form fields, they are registered in the dictionary with the input´s id. For example, the address line 1 would be:

//Shopify´s form fields using their id
$checkout.fields["checkout_billing_address_address1"]

//$checkout created fields using the field´s name given upon creation
$checkout.fields["checkout_attributes_fieldName"]

4.1. General field methods

Get input value

console.log(field.value);
field.value = '';

Add an error message and color

You can add a red border to the input and a message below it. The message can contain HTML elements in it.

field.showError('Testing error message with <b>bold</b> text!');

Remove errors

Remove the error state.

field.removeError();

4.2. TextFields

Create TextFields

import {TextField} from '@adearriba/shopify-checkout/checkout';

var field = new TextField({
    name:'dni',
    //Optional properties
    type: 'text', 
    placeholder:'DNI', 
    label:'DNI',
    size: 30, 
    defaultValue: '', 
    tooltip: 'Content of the tooltip'
});

//Accesible also from $checkout.fields
console.log($checkout.fields["checkout_attributes_dni"]);

Add tooltip to field

field.addTooltip('The content of the tooltip');

Adding it to the DOM

$checkout.fields["checkout_billing_address_phone"].insertBefore(field);

4.3. Checkboxs

Create Checkbox

import {CheckboxField} from '@adearriba/shopify-checkout/checkout';

var field = new CheckboxField({
    name:'dni', 
    //Optional properties
    label:'DNI',
    checked: true, // default: false
});

Get and set checked state

field.checked = true;
console.log(field.checked);

4.4. Dropdowns

Create a dropdown/select

import {DropdownField} from '@adearriba/shopify-checkout/checkout';

var select = new DropdownField({
    name: 'selections',
    options: [
        { text: 'option1', value: 1 },
        { text: 'option2', value: 2 },
        { text: 'option3', value: 3 },
        { text: 'option4', value: 4 },
        { text: 'option5', value: 5 },
    ],
    //optional properties
    defaultValue: 'First & disabled Option', 
    label:'Selections',
});

Get selected value

console.log(select.value);

5. Shipping methods

When the load:shipping event is triggered, the event.detail object contains the shipping methods shown to the customer.

5.1. Add description to shipping method

You can add a little description beneath the shipping method name. This accepts HTML so it can be more flexible.

$checkout.on('load:shipping', e => { 
    let shippingMethods = e.detail.shippingMethods;
    shippingMethods[0].addDescription('Shipping by <b>UPS</b>')
});

5.2. Get/set checked status

...
shippingMethods[0].checked = true;
console.log(shippingMethods[0].checked);
...

5.3. Get shipping info

The shipping method object has direct access to the shipping rate and subtotal price (lineitems + shipping rate). More data can be obtained from the methodData property.

console.log(shippingMethods[0].shippingRate);
console.log(shippingMethods[0].subtotalPrice);

console.log(shippingMethods[0].methodData);

6. Payment methods

When the load:payment event is triggered, the event.detail object contains the payment methods shown to the customer.

6.1. Add description to payment method

You can add a little description in the content box beneath the payment method radio button. This accepts HTML so it can be more flexible.

$checkout.on('load:payment', e => { 
    let paymentMethods = e.detail.paymentMethods;
    paymentMethods[1].addDescription('Payment using <b>Paypal</b>')
});

6.2. Get/set checked status

...
paymentMethods[0].checked = true;
console.log(paymentMethods[0].checked);
...

6.3. Get payment method info

The payment method object has direct access to the gateway ID and gateway name. More data can be obtained from the methodData property.

console.log(paymentMethods[0].gatewayId);
console.log(paymentMethods[0].gatewayName);

console.log(paymentMethods[0].methodData);