Add to Preferred Sources
A Shopify custom liquid block is a built-in theme editor element that lets you paste custom HTML, CSS, and Liquid code inside an existing section — such as the Product Information section on a product page — without touching a single theme file. If you run a Shopify store in South Africa, understanding the distinction between a Custom Liquid block and a Custom Liquid section is the difference between placing a payment-icon row exactly where it belongs on a product page and watching it float in the wrong position because you used the wrong tool.
Both tools live inside the Shopify theme editor, both accept the same Liquid and HTML, and both require an Online Store 2.0 (OS 2.0) theme. The difference is location and scope. A Custom Liquid section is a standalone content row you add to a page. A Custom Liquid block lives within an existing section and inherits that section's position in the page. For a South African store that needs to place a PayFast badge below the "Add to Cart" button — not below the footer — the block is the right tool.
This guide covers what each tool does, a decision table to choose between them, step-by-step instructions for both, and SA-specific use cases that make this practical rather than theoretical. Metafields and metaobjects handle structured product data; Custom Liquid handles presentation-layer customisations you cannot achieve through theme settings alone.
Quick Answer
A shopify custom liquid block is a code-insertion element you add inside an existing section in the theme editor — useful for placing a trust badge, POPIA notice, or review widget in a specific position within a page layout. A Custom Liquid section is a standalone content row added at the page level.
Both require an OS 2.0 theme and accept raw HTML, CSS, and Shopify Liquid. Choose the block when you need content inside a section (e.g., below the Add to Cart button on a product page); choose the section when you need a full-width standalone content row.
Jump to Section
How the Custom Liquid Block Works
Block vs Section — Decision Table
How to Add a Custom Liquid Block (7 Steps)
Not sure which theme customisation approach your store needs?
Share your current setup and the outcome you're trying to achieve — we'll tell you whether a Custom Liquid block, a section, or a theme file edit is the right call.
Get a Free AssessmentHow the Shopify Custom Liquid Block Works in the Theme Editor
The Custom Liquid block is a code-input element that merchants can add inside any section that supports blocks in the Shopify theme editor. It accepts raw HTML, CSS, and Shopify Liquid — the same templating language that powers the rest of your theme — and renders the output exactly where you drop it within the section.
Shopify's Online Store 2.0 architecture introduced this feature. In OS 2.0 themes, sections are made up of smaller units called blocks — you can think of a section as a container and blocks as the items inside it. Understanding the shopify theme editor custom liquid options — two separate entry points, block and section — is the starting point for getting placement right.
Most modern sections in themes like Dawn, Craft, or Sense allow you to click "Add block" and choose from a list that includes "Custom Liquid" alongside standard options like Text, Image, and Button. Once added, a text field appears in the left panel of the theme editor where you paste your code. The theme renders the output in real time on the preview canvas.
The Custom Liquid section works on a different level. Instead of living inside another section, it is its own row on the page with independent colour-scheme and padding controls. Shopify's Dawn reference theme ships with a custom-liquid.liquid file that includes three configurable settings: a Liquid code editor field, a colour scheme selector, and padding-top/bottom range sliders (0–100px). That independence makes the section the right choice when you need a standalone content row. The block is the right choice when you need content inside an existing section layout.
OS 2.0 Theme Check
In your Shopify admin, go to Online Store → Themes. If you see a Customize button alongside your theme and your theme was released after June 2021, it is likely OS 2.0. Older "vintage" themes (Debut, Brooklyn, Simple) do not support Custom Liquid blocks or sections via the theme editor — you must edit .liquid files directly. If your theme predates OS 2.0, the fastest path forward is switching to a free OS 2.0 theme like Dawn before attempting any of the steps below.
Custom Liquid Block vs Section — Which One to Use
The right tool depends on four variables: where on the page you need the content, whether it needs to appear on multiple pages, whether you need editable settings in the theme editor, and whether your theme supports blocks in that section.
| Constraint | Custom Liquid Block | Custom Liquid Section | Direct .liquid File Edit |
|---|---|---|---|
| Content must sit inside an existing section (e.g., Product Information) | ✓ Best fit | ✗ Wrong level | ✓ Possible but overkill |
| Content is a standalone full-width row | ✗ Wrong level | ✓ Best fit | ✓ Possible but overkill |
| Need to reuse on multiple pages | ✗ Page-specific only | △ Add manually to each page | ✓ Build once, reference everywhere |
| Need merchant-editable settings (text fields, images) | ✗ No settings panel | ✓ Colour, padding, Liquid editor | ✓ Full JSON schema control |
| OS 2.0 theme required | ✓ Yes | ✓ Yes | ✗ Works on any theme |
| Risk of losing on theme update | Low (saved in theme settings) | Low (saved in theme settings) | High (file may be overwritten) |
| Developer required | ✗ Merchant can self-serve | ✗ Merchant can self-serve | ✓ Liquid + JSON schema knowledge needed |
The practical rule used by the Shopify community: "Sections are rooms; blocks are furniture inside a room." If you need to place something inside an existing room (the Product Information section, the Featured Collection section), use a block. If you need to add a new room to the floor plan, use a section. If the room itself doesn't exist yet and you need it to work across the whole house, edit the .liquid file.
The One-Sentence Rule
Use the custom liquid block theme editor path (Add block inside a section) when your content must sit at a specific position within an existing section — such as between the price and the buy button on a product page. Use the section path (Add section at page level) when your content needs its own full-width row on the page. Everything else follows from this distinction.
How to Add a Custom Liquid Block to a Section (7 Steps)
When you add custom liquid Shopify presents two entry points in the theme editor: a block slot within an existing section, or a section slot at the page level. Adding a Custom Liquid block within an existing section is the most common customisation for product pages — it lets you place content at a specific position relative to the product title, price, or Add to Cart button without disrupting the section's layout.
- Open the theme editor. In your Shopify admin, go to Online Store → Themes → Customize.
- Navigate to the right template. Use the template selector at the top of the editor to open the correct page — for product-page additions, select Products → Default Product.
- Click on the target section. In the left panel, click the section you want to add the block inside — commonly the "Product Information" section. The section will expand to show its existing blocks.
- Click "Add block." At the bottom of the expanded section in the left panel, click the Add block button. A picker will appear listing available block types.
- Select "Custom Liquid." If your theme supports it, you will see a "Custom Liquid" option in the block picker. Click it to add the block to the section.
- Paste your code. The left panel will show a Liquid code input field. Paste your HTML, CSS, and/or Liquid code into this field. The preview canvas updates in real time.
- Reorder and save. Drag the block up or down within the section to position it relative to other blocks (e.g., place it after the Price block and before the Add to Cart button). Click Save.
How to Add a Custom Liquid Section (Standalone Content Row)
A shopify custom liquid section is the right approach when the content needs its own row on a page — a promotional banner, a custom testimonial strip, or an embedded video that sits between sections rather than inside one. Unlike the block, which is nested within an existing section's layout, the section stands alone on the page with its own colour scheme and padding settings.
- Open the theme editor and navigate to the page you want to modify.
- Click "Add section" in the left panel sidebar.
- Search for "Custom Liquid" in the section picker and select it.
- Paste your code into the Liquid editor field that appears in the left panel.
- Adjust colour scheme and padding using the built-in controls (available in themes like Dawn).
- Drag the section to the correct position on the page using the handle in the left panel.
- Click Save.
A Custom Liquid section is merchant-editable through the theme editor, so changes — including text, code, and padding — survive theme version updates because they are stored in your theme settings, not in the theme files themselves. This is a meaningful advantage over embedding code directly in .liquid files, where a theme update from the theme developer can overwrite your changes.
Building a Shopify product page that converts in the SA market?
We review your current theme structure and identify which customisations genuinely need a developer and which your team can handle directly in the editor. No obligation — response within 24 hours.
Request a Store ReviewSA-Specific Use Cases for the Custom Liquid Block
South African Shopify stores face customisation requirements that global guides do not cover. Because Shopify Payments is not available in South Africa, local merchants rely on third-party gateways — PayFast, Ozow, Peach Payments, and Yoco — and need to display trust icons for these providers near the checkout button. A Custom Liquid block inside the Product Information section is the most precise placement method.
| SA Requirement | Custom Liquid Block Position | What the Code Does |
|---|---|---|
| Payment-method trust icons (PayFast, Ozow, Yoco; SnapScan icon displayed as a payment method processed via PayFast) | Below the Buy button block in Product Information | Renders inline SVG icons or image tags for supported payment methods |
| POPIA processing notice | Below the Add to Cart button or in the cart drawer | Short text block confirming data is processed in line with POPIA |
| ECTA 7-day return notice | Below the product description block | Text block citing the 7-day cooling-off period under ECTA section 44 |
| VAT-inclusive price callout | Below the Price block in Product Information | Liquid renders "Price includes VAT" adjacent to the displayed price |
| Promo banner (Black Friday, payday sale) | Custom Liquid section (not block) — above or below hero section | Timed HTML block with CSS countdown or promotional text |
| Embedded review widget (Judge.me, Okendo, Yotpo) | Below the description block in Product Information | App embed code within a Custom Liquid block; note: some apps prefer app blocks instead |
| Free shipping threshold notice | Below the Buy button block | Liquid conditional: if cart total below threshold, show "Add R{threshold} more for free delivery" |
ECTA and POPIA Text — What to Actually Write
Under ECTA section 44, online buyers have a 7-day cooling-off period to return goods purchased electronically (exceptions apply: perishable goods, personalised items, and unsealed digital media). A Custom Liquid block on your product page can state this right clearly and link to your full returns policy — reducing disputes and building buyer confidence with no app required.
The Liquid language gives Custom Liquid blocks access to Shopify's store data. This means your payment icon block can conditionally show only icons for gateways you have actually enabled, your price callout can pull the live product price, and your free-shipping threshold notice can calculate against the actual cart total. Static HTML cannot do this; that is the core reason to use Liquid over a plain HTML section.
Limitations to Know Before You Add Custom Code
The Custom Liquid block and section solve real problems, but they are not a replacement for proper theme development in every situation. Knowing the limits before you build prevents wasted effort.
| Limitation | Impact | Workaround |
|---|---|---|
| OS 2.0 theme required | Older themes (Debut, Brooklyn, Simple) do not show the Custom Liquid option in the theme editor | Switch to a free OS 2.0 theme (Dawn) or edit .liquid files directly |
| No settings panel for blocks | You cannot create merchant-editable fields (text inputs, image pickers) at the block level without building a proper theme block file | Use a Custom Liquid section (has colour scheme + padding controls) or build a .liquid block file for full settings control |
| Not section-specific block support | Not every section allows Custom Liquid blocks — the section developer must have enabled it in the schema | Check the section's block picker; if "Custom Liquid" is absent, you need a section instead, or a developer to update the section schema |
| JavaScript execution context | JavaScript inside a Custom Liquid block runs client-side — it executes after the page loads, not server-side. Third-party scripts (review widgets, chat tools) typically load correctly, but conflicts with the theme's own scripts are possible | Test on a duplicate theme before publishing; for critical scripts, use Shopify's app embed block approach instead |
| Not reusable across pages automatically | A block added to the Default Product template applies to all products on that template — useful. A block added to a specific product page only applies there | Add blocks at the template level (Default Product) rather than the individual product override level for global coverage |
Performance Note
Liquid rendering happens server-side — Shopify processes the Liquid code and sends HTML to the browser, which carries virtually no client-side overhead. JavaScript embedded inside a Custom Liquid block is different: it loads and executes in the browser like any other script. Practitioners note that third-party app scripts injected into product pages can add measurable load time on mobile — Custom Liquid blocks let you use lightweight, self-contained code instead of a full app, which can keep page speed in check. Test your Lighthouse score before and after any significant addition.
Why South African Businesses Choose Growth Pulse Media for Shopify
Growth Pulse Media is run by Dirk van Greuning, who built and scaled a large South African ecommerce business before founding the agency. That background means the advice here comes from someone who has paid SA payment gateway fees, dealt with POPIA notices on a live store, and made theme customisation decisions under real business constraints — not from a team that only reads the documentation.
As a registered Shopify Partner working with South African stores, we keep a deliberately limited client load so that every project gets senior attention. We work in-house — no outsourcing, no juniors running the account.
When we assess a store's theme, we distinguish between what a merchant can self-serve through the theme editor (blocks, sections), what needs a .liquid file edit (schema changes, reusable cross-template components), and what should be handled through a Shopify app or app embed block (complex integrations, scripts that must survive theme switches). That triage matters: unnecessary developer time on straightforward theme editor work is avoidable cost.
South African merchants working with SA-specific gateways and regulatory requirements need that practical context. We have it, and we apply it to ecommerce projects from planning through to post-launch optimisation.
Who This Is NOT For
Frequently Asked Questions
What is a Custom Liquid block in Shopify and how does it differ from a Custom Liquid section?
A Custom Liquid block is a code-input element that sits inside an existing section in the Shopify theme editor — for example, inside the Product Information section on a product page. A Custom Liquid section is a standalone content row added at the page level, not nested inside another section. Use the block when you need content at a specific position within an existing layout; use the section when you need a full-width standalone content area.
Does the Shopify Custom Liquid block require a developer?
For straightforward additions — a row of payment icons, a short POPIA notice, a simple Liquid-conditional price callout — no developer is required. You add the block from the theme editor, paste the code, and save. For implementations that require conditional logic accessing cart or customer data, or that need editable settings panels, a developer with Liquid and JSON schema knowledge is recommended.
Will a Custom Liquid block survive a Shopify theme update?
Yes. Code you add through the theme editor (blocks and sections) is stored in your theme's settings data, not in the theme's code files. When a theme update is applied, the code files update but your content settings — including the code in your Custom Liquid blocks — are preserved. This is a meaningful advantage over manually editing .liquid files, which can be overwritten during an update.
Can I use JavaScript in a Shopify Custom Liquid block?
You can include a <script> tag, but community practitioners note it cannot be done safely in all contexts without care — embedded scripts execute client-side after the page loads and may conflict with the theme's own event system. The Liquid portion renders server-side; only the JavaScript is client-side. Test on a duplicate theme before publishing. For anything beyond lightweight, self-contained code, Shopify's app embed block approach is more reliable.
What Shopify themes support the Custom Liquid block?
Any Online Store 2.0 theme supports the Custom Liquid section. Whether a specific section within that theme exposes a Custom Liquid block option depends on how the section developer built its schema — most well-maintained free and premium themes (Dawn, Craft, Sense, Refresh, Ride) include it in their core sections. Older "vintage" themes (Debut, Brooklyn, Simple) do not support Custom Liquid blocks or sections via the theme editor.
Get Your Shopify Store Reviewed by a Registered Shopify Partner
Growth Pulse Media works with South African Shopify stores that need their theme, customisations, and marketing working together — not separately. We review your current setup, identify the right customisation approach for your specific requirements (block, section, or theme file), and implement it in-house with SA payment gateways and regulatory requirements accounted for. No obligation — we'll get back to you within 24 hours.
Book a Free Store Audit