shopify app
Builder.io can work elegantly with any Shopify theme and you an extend any part of your content with custom code.
Builder generates code and theme files to allow powerful editing of your store. For more information on what that code looks like and how to customize what changes Builder can make to your theme (including use metafields instead of files or only rendering client side), check out this doc on code generation options.
Tip: When using the default code generation option, Builder writes code to your store's theme. If you are using any sort of version control outside of the Shopify admin, or are pulling your theme down to develop locally and then pushing changes back up, you will need to make sure you pull the latest from your production theme to ensure all Builder created files will not be overwritten or deleted. If you push new theme code that removes the Builder created files, Builder created sections or pages may disappear or malfunction.
Any CSS of your theme automatically applies to your Builder.io content. For example, adding a Button will inherit any button { ... } styling in your theme. Same with any fonts or typography, fonts automatically inherit, and choosing "heading 1" or "heading 2" in the rich text editor will apply your h1, h2, etc fonts
You can also apply any CSS classes from your theme CSS to any layer in Builder. Just select the layer and from the style tab on the left scroll to "css classes" in the "advanced" section and apply them. You can also them save these layers as templates so your editors can have an easy selection of templates (e.g. "button bold", "hero", etc) to choose from with all of the classes and somem example content already applied
You can customize every part of the Builder.io editor with custom javascript - for example click actions, data bindings, etc. We have several useful guides on this, including:
The product box is an inline symbol, and has its own contained state separate from the content state.
The default Shopify blocks, like the Product Title block, use element data bindings in the data tab to access product information from this contained state.
If you add an on-click event to any element inside a product box and log the state to the console, you can see all of the data available in the product box state. This includes product tags, variants, associated images, and other product information.
This example shows how you can use data available in the product box state to customize your content.
To bind product images in a gallery to the selected product variant, you can check if the alt text for the selected product variant image is equal to the alt text for each image in the gallery.
- First you will need to set the alt text for each product image in Shopify so that each image that shows a certain variant has the same alt text.
- In your editor, add a new product box to the page and select any template with a product image gallery.
- Select the Image layer from inside the product image gallery.
- In the element data bindings section of the data tab, the image should already have a "Show if" binding connected to state.productInfo. Select the "edit code" button to the right of state.productInfo and replace the code with the code below:
return (state.productInfo && state.imagesItem.alt === state.selectedProductVariant.image.alt)By default, you cannot access a page or section's content state from any elements inside a product box.
To be able to view the state, you need to toggle the "Inherit State" option for the product box. You can find this by clicking on the bottom "Show Advanced" button in the product box options.
To update the parent state from an element inside the product box, you must use a nested object. In the custom JS section for the page, initialize a state variable called nested as an empty object.
state.nested = {}Select an element in the product box where you want to update the state. Add an on-click event in the data tab, and use the nested object to set the state.
state.nested.color = "red"You can find the "Edit Bootstrap code" button under the "Show Advanced" button for the page fields section in the options tab. For landing pages, this section will be blank by default.
For all other Shopify page models, this section will already have some code here specific to that page model. There is also custom javascript already on the page that connects the bootstrap code to the content state.
Following the pattern used in these page models, you can edit the bootstrap code to pull in additional data from Shopify using liquid code. If you do this, you will also need to save this data to the content state in the custom javascript code for the page.
Examples from the Builder forum:
If you create custom elements such as demonstrated in the Dawn theme code you can easily register those for use in Builder's drag and drop editor. You can learn now to do that here.
For instance, if you have an element like this
<my-hero title="Hello world"></my-hero>That you defined something like this
class MyHero extends HTMLElement { /* ... */ }
customElements.define('my-hero', MyHero)You can register it with Builder like below:
<script>
// When the SDK loads
window.builderWcLoadCallbacks = [
(context) => {
// Register each component
context.Builder.registerComponent({}, {
name: 'My Hero',
tag: 'my-hero',
inputs: [
{ name: 'title', type: 'string', defaultValue: 'Hello world' },
]
})
}
];
</script>
Learn more about our webcomponents SDK.
Also note that it's easy to wrap components of your favorite framework as custom elements, for instance see how to:
You can add Liquid code anywhere onto your Builder pages and content. The simplest way to do go to the "insert" tab in the Visual Editor and drag in a "Custom Code" block. You can then add any custom Liquid code directly there. Note: custom liquid code is only run on Shopify server render, so it will not display or be available in the Builder preview. It will run on the published page.
You can then save these as templates to make dropping in the same code easy to other similar pages
Custom Liquid components are useful for when you want to (or need to) create custom components or functionality using Liquid code. For example you might want to create a custom product cell and control all the logic and styles within Liquid code that lives in your theme, but you want to give other non technical people on your team the ability to customize (e.g. change the product, customize text, etc) and use the component within content they are creating inside of Builder.
👉Note: Custom Liquid components are powerful and useful. However, we do not suggest using them for everything. We suggest using them in situations where you need to provide specific functionality or ensure a component has very specific on brand styling that you do not want your non-technical teammates to be able to edit in the Builder editor. For re-usable components that you want all your teammates to be able to edit, or liquid components with many or very long inputs, we suggest using breaking them up into smaller components or using templates and symbols
One important thing to consider when evaluating whether or not to use custom liquid components or instead create re-usable content like symbols within Builder is how much do you want your team to be able to edit the content. If you are creating something like a carousel slider for your homepage and would like your non technical team to be able to edit pretty much anything using the Builder drag and drop editor, it makes more sense to build that content within Builder as a symbol or template. If on the other hand you want to build a complex component that you want to live within your theme code, and only want your team members to change minor things like the title or background image, creating a custom liquid component probably is the right approach. This doc on when to use what goes into a little more depth and can help you decide what to use.
To create Liquid components, create a new file matching the pattern snippets/*.block.liquid , e.g. snippets/hero.block.liquid. Note: in order for custom Liquid components to function properly within Builder, you will need to create them as a snippet, not a section.
Then, in your file, add a {% comment schema %} tag defining a schema for your custom block. Your block and be as simple as only having a name, or it can have inputs as well. Just keep in mind the contents of this {% comment schema %} tag must be valid JSON.
Then, to add this component to your page, from the "insert" tab on the left in the Visual Editor, scroll down to "liquid snippets", and drop in your snippet
Note that when you update your snippet all content in Builder referencing this snippet will automatically update, as the code they generate uses include , e.g. {% include 'hero.block' %}
The input schema for custom Liquid components is essentially the same as what we define for use by our docs on custom React components. To learn more about the options you have when specifying input schemas, see our guide for custom components here
You can add custom sections with section models for drag and drop editable content areas of your Shopify theme. These are great for carving off part of your storefront for editor control - such as site-wide ribbons, cart upsells, custom collection and product page editable areas (hero, editorials, etc).
See our step by step guide for creating a component model for a site-wide ribbon here
Shopify released the Online Store 2.0 (also know as "Sections Everywhere") update that allows developers to create themes with re-usable and user customizable sections. If you would like to integrate a Builder section (model) in to an Online Store 2.0 theme you are working on, you can create a new section in the sections folder of your theme and include a tag to render the Builder model. Here is an example on how to implement it for a Builder model named my-model:
{% render 'my-model.builder' %}
{% schema %}
{
"name": "builder-section-my-model",
"tag": "section"
}
{% endschema %}Ask us anything in our forum - we reply quickly and thoroughly!
