Update: The latest version of our Shopify Theme Updater App now supports migrating over basic customizations under select circumstances. However, the tips below are still best practices to make organizing your code easier and ensuring smooth updates.
Shopify themes from Out of the Sandbox already come packed with tons of great features that are easy to configure using the built-in configuration panel — but there comes a time in many online stores' lives when a more advanced customization is needed.
Of course, these types of customizations aren’t for the faint at heart — they do require knowledge of HTML and CSS as well as Shopify’s templating language, Liquid.
However, Shopify’s excellent documentation often suggests these types of changes and they even will sometimes provide the code needed, so this is a good concept for any Shopify store owner to know.
One of the biggest pitfalls of making updates to the code of your Shopify theme, however, is that they likely will get overwritten if you ever update your theme in the future.
Most theme publishers, including Out of the Sandbox, provide regular theme updates to add new features, support compatibility of new Web technologies or fix bugs that are discovered, so keeping your theme up-to-date certainly has its advantages.
Before you customize
It’s worth noting that, before you start any advanced customizations, to consider the pros and cons of making these types of changes. How vital is the change you are thinking about making? Also consider if there’s a way to accomplish the adjustment using one of the theme’s built-in settings in a way that doesn’t require code wrangling.
These questions are all worth weighing since, even with the tips contained in this document, there are always downsides to modifying code.
Finally, it’s worth remembering that you should always save backups of your theme at each stage. Although Shopify does offer an edit history, you never know if it will work correctly and it’s always better to have a fallback copy of your own.
A few notes before you begin
Modifying themes using the methods discussed in this post do require at least intermediate knowledge of CSS, HTML, liquid and coding principles in general, so be sure you’re comfortable with those areas before attempting any.
If you need an intro to CSS and HTML, try this CSS intro guide and this HTML intro guide. There are also tons of great resources and online classes, both free and paid, that you can find with a simple search.
If not, consider hiring a third party expert to help customize the theme.
And, just to re-emphasize this point, always make sure you have a backup of your theme files that you know works so you can revert to that if needed.
If you run into issues, a good place to start is the Shopify Forums, where you can get free advice from other users.
Custom CSS
One of the simplest ways to make adjustments is via CSS. This is probably the least destructive method as well. These types of changes are best if you need to adjust the color, font, size, spacing or placement of elements that aren’t controllable by the theme’s options panel.
To get started doing this, you can add custom CSS to the end of the styles.scss.liquid file.
- Access the Themes area of your admin panel and click the “more” icon in the upper right (this looks like three dots). Then select Edit HTML/CSS from the flyout menu that appears (shown above).
- You’ll now see Shopify’s theme file manager, which has a narrow white bar just to the right of the Shopify admin bar (see image below this list for details). Scroll down in this toolbar until you see the Assets folder and click on it to expand it if necessary.
- Click the file styles.scss.liquid and scroll all the way to the bottom. Add your custom CSS code here.
- Now, any styles you add to the custom-styles.css.liquid asset, including overrides, should overwrite any of the themes built-in styles thanks to CSS’s precedence rules.
Custom code and template modifications
Some customizations, however, take a bit more than just changes to how things look.
For example, you may need to add a custom block of text to some of your pages to give users more information or add functionality (one example seen frequently is to add a block of text and images to promote PayPal’s Bill Me Now offering).
To do this in an easy way that’s also easy to add back in after a theme update, you can make use of Shopify theme snippets by following these steps:
- Access the Shopify theme file manager as described above.
- Select the Snippets folder and click to expand if necessary. Then click Add a New Snippet.
- Enter a name for your snippet. For consistency and ease-of-use, it’s a good idea to stick to lowercase letters and replace spaces with hyphens. Also use a descriptive name so you’ll know which snippet is which.
- Click Create snippet and you should see a blank file. Add any HTML code in here, which can also include Liquid tags. Save your work.
- Now, locate the Templates folder (or, if you want to add this custom code on a site wide basis, find theme.liquid in the Layout folder). Locate the file that controls the page type you want to add this custom code to. For example, if you want to add this custom code to your product pages, find product.liquid.
- Click the file you want to edit and it will open in the right side of the screen. Now, hunt around in the code for to find where the custom code should be added. Once you locate it, place your cursor there and add this include code:
{% include 'snippet-name' %}. You’ll want to replacesnippet-namewith the name you gave the custom code snippet in step 3. - Click save and preview your work. The new code should now appear in the location you added the special tag to.
Time to update?
When it comes time to update, you’ll want to follow Shopify’s excellent guide here for some tips on what is, unfortunately, a bit of complex process.
Once you’ve completed these steps, you’ll need to take some steps to restore your customizations.
- First, move the custom code from the end of the styles.scss.liquid file to the new theme version.
- Second, manually recreate any snippet files and copy and paste the custom code from your old theme to the new copies.
- Next, update any Liquid files with references to Snippet files or other customizations.
Log your changes
As you can see, any upgrades still require some manual updating, so I like to maintain a list of every custom CSS and snippet modification a theme uses along with the filenames and line location where the include tags need to be added.
Although the line numbers may vary slightly when a theme is updated, at least you’ll have a good idea of where to start looking.
Advantages
Although these techniques may seem a bit complex, because you’re isolating the custom code you create into separate files, it’s also a lot easier to maintain them when updating a theme. Imagine if you went in and customized dozens of different CSS declarations all over the theme’s CSS file or added HTML code directly to all of your theme’s Liquid files in multiple locations. It would be a nightmare to keep track over where every change you made is.
In addition, these techniques have the added advantage that, should you run into compatibility issues with your customizations, you can easily remove the include tags temporarily as a well to isolate the issue.
