Best practices for editing checkout.liquid
If you're on Shopify Plus, then you can get access to the
checkout.liquid layout. However, if you make changes to this layout, then you'll need to manually upgrade it whenever Shopify releases an upgrade.
Document Object Model (DOM) dependencyAnchor link to section titled "Document Object Model (DOM) dependency"
One of the biggest considerations to make when implementing checkout modifications is how DOM-dependent your code is. As Shopify releases checkout upgrades, the content output by the Liquid drops in
checkout.liquid, and in some cases by the
checkout.liquid content itself, is updated. This means that if your customizations depend on that content, then they could break with new upgrades. It’s always best to minimize DOM dependency to reduce future support debt for your team.
Add custom codeAnchor link to section titled "Add custom code"
When making changes, you should keep all of the relevant code for a specific customization in a single snippet. This reduces the risk of conflict with other code, and generally makes the code easier to read.
Also, any time that a change is made, it's recommended that you place a comment at the beginning of the change noting who made it, and when.
Add killswitchesAnchor link to section titled "Add killswitches"
checkout.liquid, you're more likely to run into issues or conflicts in the checkout, possibly preventing sales, so it's a good idea to wrap your customizations in a killswitch (a theme setting). This allows you to temporarily disable the customization to get the checkout functioning quickly, which gives you time to troubleshoot issues.
General customization approachAnchor link to section titled "General customization approach"
In general, the approach for making customizations is the following:
- Create a killswitch theme setting
- Create a snippet to host your customization
- Include your snippet, wrapped in your killswitch, in
The following examples show a killswitch theme setting and a snippet inclusion wrapped in a conditional based on the killswitch:
In your snippet, you can do the following:
- Use the checkout's version of jQuery
- Watch for the
page:changeevents to set up your customization
- Scope your customization to the appropriate step or page by referencing the following objects:
Form submitAnchor link to section titled "Form submit"
Many checkout customizations require validating data before allowing the customer to move to the next step. Due to the functionality around the main form submit button, the easiest approach is watch for the
click event on this button, rather than the
submit field on the form. You should also watch for the use of the enter key and re-route that functionality into a
click event on the submit button.
Common customizationsAnchor link to section titled "Common customizations"
The following examples are commonly requested customizations. They all use the general customization approach as a starting point.
Block the use of specific characters in address fieldsAnchor link to section titled "Block the use of specific characters in address fields"
To block the use of specific characters in address fields, you need to consider the following cases:
Updates to the associated address fields, such as the
The form submit event.
For each of these cases, execute your validation. For example, you could compare any field values with a Regular Expression (Regex). If the data isn't valid, you can show an error and prevent the default functionality.
Limit the number of characters in address fieldsAnchor link to section titled "Limit the number of characters in address fields"
To limit the number of characters in address fields, add a
maxlength attribute to any associated fields, as shown in the following example.
maxlength attribute only prevents additional characters from being entered. To ensure a good user experience, you should add a message that appears when a customer hits the character limit.
Add a required Terms of Service checkboxAnchor link to section titled "Add a required Terms of Service checkbox"
To add a required checkbox for agreeing to Terms of Service, create a checkbox on the page, then follow the form submit event to check whether the checkbox has been checked before allowing the customer to proceed. It's also a good idea to use a checkout attribute to save the value of the checkbox.