{"article":{"id":13706877408796,"url":"https://nshift.zendesk.com/api/v2/help_center/en-us/articles/13706877408796.json","html_url":"https://helpcenter.nshift.com/hc/en-us/articles/13706877408796-nShift-Checkout-widget-integration","author_id":114867042794,"comments_disabled":true,"draft":false,"promoted":false,"position":0,"vote_sum":0,"vote_count":0,"upvote_count":0,"downvote_count":0,"section_id":13706000163740,"created_at":"2024-04-25T09:28:31Z","updated_at":"2026-05-11T11:19:05Z","name":"nShift Checkout widget integration","title":"nShift Checkout widget integration","source_locale":"en-us","locale":"en-us","outdated":false,"outdated_locales":[],"edited_at":"2025-12-09T10:30:06Z","user_segment_id":null,"permission_group_id":1006554,"content_tag_ids":[],"label_names":[],"body":"<p><img src=\"https://helpcenter.nshift.com/hc/article_attachments/13712629218204\" alt=\"nshift-checkout-label.png\"></p><p><br>This article will explain how to add the nShift Checkout widget to your web page so you can graphically present the different delivery options in your webshop.<br><br> </p><p>Content in this article:</p><ul>\n<li data-list-item-id=\"eb8b0e3c1c8b5139b17f4ebdd3ee6f193\"><a href=\"#h_01HWA8NMH9RBR480B959QZ9Z0B\">Add links to the widget files</a></li>\n<li data-list-item-id=\"efbdbeaceca82840e425121d585a9ca5a\"><a href=\"#h_01HWADGAT43AYH56SV8PDW76DN\">Create the widget on the page</a></li>\n<li data-list-item-id=\"e62146ef2ceccf7d9d7d0af12cec3a2f0\"><a href=\"#h_01HWAQWMXTTWMBM85CTG8TPHVQ\">Show the widget</a></li>\n<li data-list-item-id=\"e740213eae7bd8505f92696788ce133f7\"><a href=\"#h_01HWARWD1Q5DYMSYV4Z122XGNN\">Fill the widget with shipping options</a></li>\n</ul><p> </p><figure class=\"wysiwyg-table wysiwyg-table-align-left\"><table style=\"border-spacing: 5px; border-style: solid; border-width: 1px;\"><tbody><tr style=\"background-color: #ffffcc;\"><td style=\"border-style: solid; border-width: 1px; padding: 5px 5px 5px 7px;\">\n<span style=\"color: #FF0000;\">Important note: </span>The nShift Checkout widget cannot be used with Delivery Checkout (legacy version). Read more about the legacy widget <a href=\"https://helpcenter.nshift.com/hc/en-us/articles/7632204928668\">here</a>. </td></tr></tbody></table></figure><p> </p><hr><h2 id=\"h_01HWA8NMH9RBR480B959QZ9Z0B\">Add links to the widget files</h2><p>Two files must be included in the web page for the widget: a JavaScript file that contains the widget code and a CSS file that adds the styling of the widget.</p><p> </p><p>Link to the JavaScript file with a script tag:</p><pre class=\"wysiwyg-code-block\"><code class=\"language-auto\">&lt;script src=\"https://www.nshiftportal.com/checkout/widget/nshift-checkout-widget.js\"&gt;&lt;/script&gt;</code></pre><p>The JavaScript file will include additional JavaScript files on demand when the widget is added to the page. If this causes any problems, the alternative file nshift.checkout-widget.all.js can be used. It contains all of the code for the widget in a single file.</p><p> </p><p>Link to the CSS file with a link tag:</p><pre class=\"wysiwyg-code-block\"><code class=\"language-auto\">&lt;link rel=\"stylesheet\" href=\"https://www.nshiftportal.com/checkout/widget/nshift-checkout-widget.css\"&gt;</code></pre><p>To simplify styling the widget, it might be beneficial to place the link to the CSS file before any links to CSS files that contain rules that override widget styling.</p><p> </p><p><strong>Hosting the files locally</strong></p><p>An alternative to linking to the widget files on nShift servers is to host the files locally. In that case, the nshift-checkout-widget-all.js file should be used together with the normal nshift-checkout-widget.css file.</p><p>Note that the main downside to hosting the file locally is that any updates to the widget by nShift will not become available until the hosted files are updated. The advantage is that the widget will be available on the web page even if there is a problem reading the files from nShift servers. In a fallback solution, this might be an important aspect.</p><p> </p><p> </p><h2 id=\"h_01HWADGAT43AYH56SV8PDW76DN\">Create the widget on the page</h2><p>With the JavaScript code for the widget loaded into the page, the actual widget can be created like this:</p><pre class=\"wysiwyg-code-block\"><code class=\"language-auto\">var widget = nShiftCheckoutWidget.createWidget(containerElement, widgetSettings);</code></pre><p><br><strong>Container Element</strong><br>The container element argument to the <strong>createWidget</strong> function is either an actual HTML DOM element object that will be the parent of the widget. Or it can be a string containing a selector for the HTML DOM element. The selector string will be used in a call to document.querySelector to find the element.</p><p> </p><p><strong>Widget Settings</strong><br>The widget settings argument to the <strong>createWidget</strong> function is a JavaScript object with the following structure:</p><p> </p><pre class=\"language-json\">{\n  \"widgetVersion\": \"2\",\n  \"theme\": \"nshift-theme1\",\n  \"themeOverride\": {\n    \"showLogos\": true,\n    \"showMap\": true,\n    \"showPickupPointInfo\": true,\n    \"showCategories\": true,\n    \"showOriginalPrices\": true,\n    \"showDeliveryTime\": true,\n    \"selectFirstAvailableOption\": true,\n    \"numberOfAlwaysVisibleTextLines\": 1,\n    \"numberOfInitiallyVisibleOptions\": 1\n  },\n  \"mode\": \"standard\",\n  \"widthBreakpoints\": {\n    \"narrow\": 400,\n    \"ultra-narrow\": 300\n  },\n  \"popupContainerElement\": \"document.querySelector('#root')\",\n  \"resizeCallback\": \"(function(size) {\n  })\",\n  \"resultCallback\": \"(function(result) {\n  })\",\n  \"accessibilityChangeCallback\": \"(function(diff) {\n  })\",\n  \"accessibilityValidationCallback\": \"(function(message) {\n  })\"\n}</pre><p> </p><ul>\n<li data-list-item-id=\"e3051c12a31838b03d05e3f1ff5305fef\">\n<strong>widgetVersion </strong>- This property must currently always be the string \"<em>2</em>\" to indicate what version of the widget is expected.<br> </li>\n<li data-list-item-id=\"e76534185f4d5b4c5bdcaa712b1bc3ea6\">\n<strong>theme </strong>- The name of the styling theme is optional, and the only valid theme right now is \"<em>nshift-theme1</em>\"<br> </li>\n<li data-list-item-id=\"e41cd32b37a4f56a5dcb9dd9ba541045d\">\n<strong>themeOverride </strong>- The sub object containing changes to the selected theme is optional.<ul>\n<li data-list-item-id=\"e46d203616a9c48f3b06837ad92fc2a3a\">\n<strong>showLogos </strong>- If this property is set to <em>false,</em> no carrier logos will be shown in the widget.<br> </li>\n<li data-list-item-id=\"e5d4cbed89c498882ca67adda19c6a672\">\n<strong>showMap </strong>- If this property is set to <em>false,</em> no map will be shown when selecting pickup points in the widget.<br> </li>\n<li data-list-item-id=\"e6e958d0584b364a68268646f5154377a\">\n<strong>showPickupPointInfo </strong>- If this property is set to <em>false,</em> no additional information for pickup points will be shown.<br> </li>\n<li data-list-item-id=\"ec4d73fd756eb5a6d893765fe2cb63b37\">\n<strong>showCategories </strong>- If this property is set to <em>false,</em> no category headers will be shown in the widget.<br> </li>\n<li data-list-item-id=\"ecedfbda4ba60ae1ce4966a5925ddf085\">\n<strong>showOriginalPrices </strong>- If this property is set to <em>false,</em> no original prices will be shown next to the normal price in the widget.<br> </li>\n<li data-list-item-id=\"ea4badc326672ad062de78d48e570a8ed\">\n<strong>showDeliveryTime </strong>- If this property is set to <em>false,</em> no delivery times will be shown in the dedicated delivery time fields of the widget.<br> </li>\n<li data-list-item-id=\"e42f3df945292eda3cd886018cb0de2a1\">\n<strong>selectFirstAvailableOption</strong> - If this property is set to false, the first option is no longer automatically selected.<br> </li>\n<li data-list-item-id=\"e92e34f81fd95ca8ec1161e528b37b043\">\n<strong>numberOfAlwaysVisibleTextLines</strong> - It is possible to set a value between 1-4 to display text fields 1-4 without an option being selected.<br> </li>\n<li data-list-item-id=\"efca49ee2edd3e345def27890085e5fb5\">\n<strong>numberOfInitiallyVisibleOptions</strong> - Any options after this number of options will initially be hidden. If this property is missing or set to undefined, then there is no limit, and all options will always be shown. <br> </li>\n</ul>\n</li>\n<li data-list-item-id=\"e27a9c122323b4ba1d2f95a6ebc2eec89\">\n<strong>widthBreakpoints </strong>- The subobject for width breakpoints is optional. If it is provided, it should contain keys and width values. The key with the smallest width value less than the width of the widget will be selected. The selected key is combined with the prefix \"<em>nshift-breakpoint-</em>\" and added as a CSS class to the toplevel widget element. This can be used to adjust styling based on the width of the widget on the web page.<br> </li>\n<li data-list-item-id=\"e123233d1fe9d2f0ca365df23a717d669\">\n<strong>mode </strong>- This property can be set to \"standard\" for the normal widget, or to \"product\" to get the read-only product page widget. <br> </li>\n<li data-list-item-id=\"eed527dec4e7cb775175a4069566c3ad3\">\n<strong>accessibilityChangeCallback</strong> and <strong>accessibilityValidationCallback </strong>- These optional properties can be used to coordinate accessibility messages into a page-wide live region. If either callback is missing, the widget will create and use a live region element inside the widget container. <br> </li>\n<li data-list-item-id=\"ee48bb273b169066c0ac2d9a42bb2e6eb\">\n<strong>popupContainerElement </strong>- This property is an optional HTML DOM element that should be used as the parent of any popup dialog created by the widget. If no element is provided, the widget code will create a div element as a direct child of the body element.<br> </li>\n<li data-list-item-id=\"e7cc98f99774f7ac093e4201d3ec3afb5\">\n<strong>resizeCallback </strong>- This optional callback function will be called when the size of the widget changes. The <em>size</em> argument is an object with the properties <em>w</em> and <em>h</em> for width and height.<br> </li>\n<li data-list-item-id=\"e667ab81cd4c604e80d1007087496ee0d\">\n<strong>resultCallback </strong>- This optional callback function will be called whenever a user changes something in the widget. This includes selecting a shipping option, but also entering text in a field like a phone number.</li>\n</ul><p> </p><h2 id=\"h_01HWAQWMXTTWMBM85CTG8TPHVQ\">Show the widget</h2><p>To get the widget to show up on the web page, the method <strong>install</strong> must be called on the widget instance. This will create the HTML elements that make up the widget inside the container element.</p><p> </p><pre class=\"wysiwyg-code-block\"><code class=\"language-auto\">  var widget = nShiftCheckoutWidget.createWidget(containerElement, widgetSettings);\n  widget.install();</code></pre><p><br>If there is a need to remove the widget from the page, this can be done by calling the uninstall method.</p><p> </p><pre class=\"wysiwyg-code-block\"><code class=\"language-auto\">widget.uninstall();</code></pre><p> </p><p> </p><h2 id=\"h_01HWARWD1Q5DYMSYV4Z122XGNN\">Fill the widget with shipping options</h2><p>When first shown, the widget will be empty. To fill it with shipping options, the widget must be updated with data from the shipping options endpoint of the nShift Checkout REST API. The updateOptions method of the widget instance takes the shipping options data as an argument and displays it in the widget.</p><p> </p><pre class=\"language-auto\">// Disable user interaction with the widget during the request for data.\nwidget.disable();\n// Fetch shipping options data from the server.\nfetch(url).then(function(response) {\n   return response.json();\n}).then(function(data) {\n   // Update the widget with shipping options data.\n   widget.updateOptions(data);\n}).catch(function() {\n   // Handle error.\n}).then(function() {\n   // Always enable user interaction with the widget.\n   widget.enable();\n});\n</pre><p> </p><p>Read about handling external and internal changes in the widget <a href=\"https://helpcenter.nshift.com/hc/en-us/articles/13711732823580\">here</a>.</p><p> </p>","user_segment_ids":[]}}