Skip to content
Docs

App blocks vs. Web Components

Every Live Component can be placed two ways. They render the same component from the same data — the difference is who places it, how it’s configured, and where it’s allowed to go.

  • App blocks — added through the theme editor. No code; every setting is a control in the editor. The right choice for most merchants, and the only way to render inside product cards on collection pages.
  • Web Components — the <dkl-*> element written directly into your theme’s Liquid. Configured with data-* attributes and --dkl-* CSS. For developers customizing a theme by hand. (These are labelled “Web Components” on each component page.)

At a glance

Section titled “At a glance”
App block Web Component
Added by Theme editor (drag-and-drop) Hand-written in theme Liquid/HTML
Configuration Editor settings panel data-* attributes
Styling Editor pickers (colours, spacing, fonts) --dkl-* CSS styling tokens
Which discount The block’s Discount picker data-discount-id attribute
Product cards / collection grids ✅ Supported ❌ Product-page only
Needs the app embed ✅ Yes ✅ Yes
No-flicker render ✅ Inline server render ✅ From a head carrier
Best for Merchants, no code Developers, full control

App blocks

Section titled “App blocks”

An app block is a theme block you add in the editor — DK: Price, DK: Volume Groups, DK: Discount Badge, or DK: Order Goal. Drop it into a section or product-card slot, and configure it entirely through the editor’s settings panel.

Online Store → Themes → Customize → (add block) → DK: Price

What an app block does for you:

  • Resolves the eligible discount itself — using the shared eligibility rules, so it agrees with the custom-tag path. When more than one discount applies, it renders the first eligible one, or a specific one chosen in its Discount picker setting.
  • Exposes every option as an editor control — colours, spacing, labels, and behaviour toggles. Your choices are written into a scoped <style> rule the block emits, so styling lives in the theme editor.
  • Only loads when it’s on the page — its stylesheet and controller load with the block.
  • Reaches contexts a tag can’t — most importantly product cards in a collection grid, where there’s no single product in <head> context to pre-stage a carrier from.

Use an app block when a merchant should be able to place and style the component without touching code, or whenever you need it inside a product card.

Web Components

Section titled “Web Components”

A web component is the <dkl-*> web component written straight into your theme’s markup:

<dkl-price></dkl-price>

By default, a web component needs zero attributes — the page’s primary product is the implicit default, and the tag clones a pre-staged carrier (markup, styling, and data-* values) before first paint. Configure it with data-* attributes and style it with --dkl-* CSS:

<dkl-price
  data-show-savings="true"
  style="--dkl-price-savings-background:#111; --dkl-price-savings-color:#fff"
></dkl-price>

What to know about web components:

  • Product-page only. Carriers exist only where there’s a single product (or the shop) in context. A collection grid is paginated and per-product, so a hand-typed tag can’t be pre-staged there — use the app block for product cards.
  • Target a specific discount with data-discount-id (the metaobject handle; the discount- prefix is optional). Place one tag per discount to show several.
  • Style with --dkl-* tokens in your own CSS — a tag has no block context, so there’s no editor panel. Set the tokens on :root, the embed’s Custom CSS, an inline style, or any ancestor. The defaults match the app block exactly, so an unstyled tag looks identical to a default block.
  • Behaviour toggles may default off. For the volume picker, native-price update and quantity sync only run if you opt in (data-update-price-on-change="true" / data-sync-with-quantity="true"); any attribute you set wins over the carrier’s.

Use a web component when you’re editing the theme directly and want precise control over placement, attributes, and CSS.

Which should I use?

Section titled “Which should I use?”

Reach for an app block

The merchant should configure it without code · you need it in a product card · you want styling managed from the theme editor.

Reach for a web component

You’re editing theme Liquid directly · you want exact control over placement and data-* · you’re styling with --dkl-* CSS · you need several discounts placed by hand.

Next steps

Section titled “Next steps”
OverviewEnabling the runtime and theming with --dkl-* tokens.
Discount PriceSee both placement paths on a real component.