{"id":24961693,"url":"https://github.com/adearriba/shopifycheckoutjs","last_synced_at":"2025-04-10T21:37:42.192Z","repository":{"id":41221127,"uuid":"330762178","full_name":"adearriba/ShopifyCheckoutJS","owner":"adearriba","description":"A little code for having a better experience manipulating Shopify´s Checkout via JS.","archived":false,"fork":false,"pushed_at":"2022-09-25T13:54:49.000Z","size":431,"stargazers_count":63,"open_issues_count":4,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-07T20:43:56.082Z","etag":null,"topics":["checkout","js","shopify"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@adearriba/shopify-checkout","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adearriba.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-01-18T19:07:19.000Z","updated_at":"2024-08-01T01:54:01.000Z","dependencies_parsed_at":"2022-08-10T01:43:14.098Z","dependency_job_id":null,"html_url":"https://github.com/adearriba/ShopifyCheckoutJS","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adearriba%2FShopifyCheckoutJS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adearriba%2FShopifyCheckoutJS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adearriba%2FShopifyCheckoutJS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adearriba%2FShopifyCheckoutJS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adearriba","download_url":"https://codeload.github.com/adearriba/ShopifyCheckoutJS/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248304940,"owners_count":21081551,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["checkout","js","shopify"],"created_at":"2025-02-03T08:56:01.654Z","updated_at":"2025-04-10T21:37:42.168Z","avatar_url":"https://github.com/adearriba.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ShopifyCheckoutJS \u003c!-- omit in toc --\u003e\nA little library that will help you manipulate Shopify´s Checkout via JS.\n\n\u003e **IMPORTANT:** Shopify Plus is needed. The resulting JS needs to be included in checkout.liquid file which is only available to Shopify Plus stores.\n\n- [Other versions](#other-versions)\n- [1. Install](#1-install)\n- [2. $checkout object](#2-checkout-object)\n\t- [2.1. Events](#21-events)\n- [3. Components](#3-components)\n\t- [3.1. General component methods](#31-general-component-methods)\n\t- [3.2. Sections](#32-sections)\n\t- [3.3. Radio buttons group](#33-radio-buttons-group)\n- [4. Fields](#4-fields)\n\t- [4.1. General field methods](#41-general-field-methods)\n\t- [4.2. TextFields](#42-textfields)\n\t- [4.3. Checkboxs](#43-checkboxs)\n\t- [4.4. Dropdowns](#44-dropdowns)\n- [5. Shipping methods](#5-shipping-methods)\n\t- [5.1. Add description to shipping method](#51-add-description-to-shipping-method)\n\t- [5.2. Get/set checked status](#52-getset-checked-status)\n\t- [5.3. Get shipping info](#53-get-shipping-info)\n- [6. Payment methods](#6-payment-methods)\n\t- [6.1. Add description to payment method](#61-add-description-to-payment-method)\n\t- [6.2. Get/set checked status](#62-getset-checked-status)\n\t- [6.3. Get payment method info](#63-get-payment-method-info)\n\n# Other versions\n\nPlease refer to each version branch in case you are using a previous verions.\n\n**Important: ``V0.2.0 has breaking changes.``**\n\nv0.1.0: https://github.com/adearriba/ShopifyCheckoutJS/tree/v0.1.0\n\n# 1. Install\n\n```javascript\nnpm i @adearriba/shopify-checkout\n```\n\n# 2. $checkout object\nThe `$checkout` object is created to help with the different tasks manipulating Shopify´s checkout page.\n\n## 2.1. Events\nTo register handlers for common events, you can use the `$checkout.on(event, callback)` function.\n```javascript\nimport { $checkout } from '@adearriba/shopify-checkout/checkout.js';\n\n$checkout.on('load', (e) =\u003e { console.log(e); })\n\n$checkout.on('load:information', function(e) { \n\tconsole.log(e); \n})\n\n$checkout.on('error', function(e) { \n\tconsole.trace(); \n})\n```\n**Loading events**\n\nThis are events related to loading or changing a page/step during the checkout process:\n|Event name|Descripcion|\n|---|---|\n|continue|Triggers whenever any of any checkout pages are submitted.|\n|load|This is triggered for convenience in every Shopify´s ``page:load`` or ``page:change`` event.|\n|load:information|**Information** step is loaded|\n|load:shipping|**Shipping** step is loaded. The ``event.detail`` object contains the shipping methods shown in the page.|\n|load:payment|**Payment** step is loaded. The ``event.detail`` object contains the payment methods shown in the page.|\n|load:processing|**Processing** page is loaded|\n|load:thankyou|**Thank you** page is loaded|\n|load:orderstatus|**Order status** page is loaded|\n|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.|\n\n\n**Interactive events**\n\nThis are events related to interactions with the UI.\n\n|Event name|Descripcion|\n|---|---|\n|shippingmethod:changed|When a shipping method is selected. The ``event.detail`` contains the [shipping method object](#4-shipping-methods).|\n|paymentmethod:changed|When a payment method is selected. The ``event.detail`` contains the [payment method object](#5-payment-methods).|\n|component:changed|When a component's value changes. The ``event.detail`` contains the component that changed.|\n|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.|\n\n\n**Other events**\n\n|Event name|Descripcion|\n|---|---|\n|error|When an exception is catch inside a callback of any triggered event|\n|field:created|When a field is **created**. The field reference is inside the ``event.detail`` property.|\n|field:removed|When a field is **removed**. The field reference is inside the ``event.detail`` property.|\n\n# 3. Components\n\n## 3.1. General component methods\n\n**Insert components into the DOM**\n\nComponents 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.\n\n```javascript\n$checkout.fields[\"checkout_billing_address_phone\"].insertBefore(field);\n$checkout.fields[\"checkout_billing_address_last_name\"].insertAfter(field);\n```\n\n**Watch for changes in components**\n\nWhen 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)``.\n\n```javascript\nfield.onValueChanged(function(event){\n\tconsole.log(event);\n});\n\nfield.on('changed', function(event){\n\tconsole.log(event);\n});\n\ncomponent.onValueChanged(function(event){\n\tconsole.log(event);\n});\n\ncomponent.on('changed', function(event){\n\tconsole.log(event);\n});\n```\n\n## 3.2. Sections\nIn 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.\n\n**Get a section that already exists**\n```javascript\n//always import the corresponding component\nimport {SectionComponent} from '@adearriba/shopify-checkout/checkout';\n\n//Using a css selector, you can create a reference to an existing section\nlet shippingFormSection = new SectionComponent({selector: '.section--shipping-address'});\n```\n\n**Create a new section and add it before/after another one**\n```javascript\nimport {SectionComponent} from '@adearriba/shopify-checkout/checkout';\n\n//Create a new Section component\nlet section = new SectionComponent({name: 'shipping-method', title: 'Shipping method'});\n\n//Add the section before or after the previous reference\nshippingFormSection.insertBefore(section);\nshippingFormSection.insertAfter(section);\n```\n\n## 3.3. Radio buttons group\n\n**Create a radiobox in a section**\n```javascript\n//Import both components together\nimport {SectionComponent, RadioContentBoxComponent} from '@adearriba/shopify-checkout/checkout';\n\n//Create a new RadioContentBoxComponent\nvar radioBox = new RadioContentBoxComponent({name: 'RadioContentBox' });\n\n//Create an option using innerHTML instead of a text label\nlet option1 = {\n\thtmlFor: 'shipping', \n\tvalue: 'shipping', \n\tinnerHTML: '\u003csvg 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\"\u003e\u003cpath 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\"\u003e\u003c/path\u003e\u003c/svg\u003eShipping'};\n\n//Using a text label\nlet option2 = {label: 'Pickup in Store', htmlFor: 'pickup', value: 'pickup'};\n\n//Add options to RadioContentBoxComponent\nradioBox.addOption(option1);\nradioBox.addOption(option2);\n\n//Add the RadioContentBoxComponent to the previous section\nsection.addContent(radioBox);\n\n//Insert the new section before the existing shippingFormSection\nshippingFormSection.insertBefore(section);\n```\n\n**Result**\n![RadioContentBoxComponent](/imgs/shipping_methods.PNG)\n\n**Get selected value**\n```javascript\nconsole.log(radioBox.value);\n```\n\n\n# 4. Fields\nFields 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}``.\n\nFor Shopify´s original form fields, they are registered in the dictionary with the input´s id. For example, the address line 1 would be:\n\n```javascript\n//Shopify´s form fields using their id\n$checkout.fields[\"checkout_billing_address_address1\"]\n\n//$checkout created fields using the field´s name given upon creation\n$checkout.fields[\"checkout_attributes_fieldName\"]\n```\n\n## 4.1. General field methods\n\n**Get input value**\n```javascript\nconsole.log(field.value);\nfield.value = '';\n```\n\n**Add an error message and color**\n\nYou can add a red border to the input and a message below it. The message can contain HTML elements in it.\n\n```javascript\nfield.showError('Testing error message with \u003cb\u003ebold\u003c/b\u003e text!');\n```\n\n**Remove errors**\n\nRemove the error state.\n\n```javascript\nfield.removeError();\n```\n\n## 4.2. TextFields\n\n**Create TextFields**\n```javascript\nimport {TextField} from '@adearriba/shopify-checkout/checkout';\n\nvar field = new TextField({\n\tname:'dni',\n\t//Optional properties\n\ttype: 'text', \n\tplaceholder:'DNI', \n\tlabel:'DNI',\n\tsize: 30, \n\tdefaultValue: '', \n\ttooltip: 'Content of the tooltip'\n});\n\n//Accesible also from $checkout.fields\nconsole.log($checkout.fields[\"checkout_attributes_dni\"]);\n```\n\n**Add tooltip to field**\n```javascript\nfield.addTooltip('The content of the tooltip');\n```\n\n**Adding it to the DOM**\n```javascript\n$checkout.fields[\"checkout_billing_address_phone\"].insertBefore(field);\n```\n\n## 4.3. Checkboxs\n\n**Create Checkbox**\n```javascript\nimport {CheckboxField} from '@adearriba/shopify-checkout/checkout';\n\nvar field = new CheckboxField({\n\tname:'dni', \n\t//Optional properties\n\tlabel:'DNI',\n\tchecked: true, // default: false\n});\n```\n\n**Get and set checked state**\n```javascript\nfield.checked = true;\nconsole.log(field.checked);\n```\n\n## 4.4. Dropdowns\n\n**Create a dropdown/select**\n```javascript\nimport {DropdownField} from '@adearriba/shopify-checkout/checkout';\n\nvar select = new DropdownField({\n    name: 'selections',\n    options: [\n        { text: 'option1', value: 1 },\n        { text: 'option2', value: 2 },\n        { text: 'option3', value: 3 },\n        { text: 'option4', value: 4 },\n        { text: 'option5', value: 5 },\n\t],\n\t//optional properties\n\tdefaultValue: 'First \u0026 disabled Option', \n\tlabel:'Selections',\n});\n```\n\n**Get selected value**\n```javascript\nconsole.log(select.value);\n```\n\n# 5. Shipping methods\nWhen the ``load:shipping`` event is triggered, the ``event.detail`` object contains the shipping methods shown to the customer.\n\n## 5.1. Add description to shipping method\nYou can add a little description beneath the shipping method name. This accepts HTML so it can be more flexible.\n\n```javascript\n$checkout.on('load:shipping', e =\u003e { \n    let shippingMethods = e.detail.shippingMethods;\n    shippingMethods[0].addDescription('Shipping by \u003cb\u003eUPS\u003c/b\u003e')\n});\n```\n\n## 5.2. Get/set checked status\n```javascript\n...\nshippingMethods[0].checked = true;\nconsole.log(shippingMethods[0].checked);\n...\n```\n\n## 5.3. Get shipping info\nThe 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.\n```javascript\nconsole.log(shippingMethods[0].shippingRate);\nconsole.log(shippingMethods[0].subtotalPrice);\n\nconsole.log(shippingMethods[0].methodData);\n```\n\n# 6. Payment methods\nWhen the ``load:payment`` event is triggered, the ``event.detail`` object contains the payment methods shown to the customer.\n\n## 6.1. Add description to payment method\nYou can add a little description in the content box beneath the payment method radio button. This accepts HTML so it can be more flexible.\n\n```javascript\n$checkout.on('load:payment', e =\u003e { \n    let paymentMethods = e.detail.paymentMethods;\n    paymentMethods[1].addDescription('Payment using \u003cb\u003ePaypal\u003c/b\u003e')\n});\n```\n\n## 6.2. Get/set checked status\n```javascript\n...\npaymentMethods[0].checked = true;\nconsole.log(paymentMethods[0].checked);\n...\n```\n\n## 6.3. Get payment method info\nThe payment method object has direct access to the gateway ID and gateway name. More data can be obtained from the ``methodData`` property.\n\n```javascript\nconsole.log(paymentMethods[0].gatewayId);\nconsole.log(paymentMethods[0].gatewayName);\n\nconsole.log(paymentMethods[0].methodData);\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadearriba%2Fshopifycheckoutjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadearriba%2Fshopifycheckoutjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadearriba%2Fshopifycheckoutjs/lists"}