Skip to content
tt-blocks Docs

FAQ

Widget not showing?

Section titled “Widget not showing?”

Check in this order:

  1. Is the app embed enabled? — Widget list → StatsRow → “App status” card should read “Enabled”. See Install and enable.
  2. Does the placement match the current page? — A widget mounted on the product page only renders on product pages.
  3. Are the Display rules too strict? — Watch the Display tab StickyBar verdict.
  4. Did the theme anchor resolve? — Verdict “No available placement on the current page” means the theme selector isn’t in the 65-theme matrix; fill customAnchorSelectors.

Full diagnostic path: Troubleshooting.

App embed enabled but the widget still doesn’t appear?

Section titled “App embed enabled but the widget still doesn’t appear?”

Common causes:

  • Theme cache — wait 30 seconds or force-refresh the browser
  • Theme not in the 65-theme matrix — use Custom Position or fill customAnchorSelectors
  • Custom Position mode without manually placing the block — see Custom placement
  • You switched themes — “Switching themes resets this toggle — you’ll need to re-enable it after changing themes.”

How does multi-language fallback work?

Section titled “How does multi-language fallback work?”

Tip: “If a locale has no content, it falls back to the default language.”

Behavior:

  • A field translated for a given locale in the Localization tab → that locale shows the translation
  • Untranslated → falls back to the default language (the column marked “Default”)
  • The storefront widget.js derives the active locale from window.Shopify.locale; only language primary tags are supported (e.g. en-US → en)

Will I lose my custom edits when I switch color schemes?

Section titled “Will I lose my custom edits when I switch color schemes?”

No. Tip: “Switching applies the selected scheme’s colors and shapes to the widget; text, layout, and items are preserved.”

Behavior:

  • Switching a bundle projects fill / iconStyle / other flat fields onto the widget config
  • Fields the merchant explicitly customized are snapshot-locked and not overwritten
  • Text, layout, and items are never touched

See Multi-axis token bundle.

What’s the difference between Pro and Free?

Section titled “What’s the difference between Pro and Free?”

Main differences:

  • UTM traffic source dimension (Pro)
  • Hide theme elements dimension (Pro)
  • Advanced CSS (Pro)
  • Full variants dimension (Free has demo quota)
  • Full products / collections dimensions (Free has demo quota — 1 entry per rule)

Full comparison: Plans. Tier mechanics: Billing tier.

How do I uninstall?

Section titled “How do I uninstall?”
Shopify Admin → Settings → Apps and sales channels
  → TT Badges & Product Labels → ⋯ → Uninstall

After uninstall the system automatically:

  • Receives the app/uninstalled webhook
  • Deletes merchant data per Privacy Policy §6
  • Disables the tt-blocks app embed in your theme

Is there a widget count limit?

Section titled “Is there a widget count limit?”
  • Free / Pro both have no limit on the number of widgets you can create
  • Shopify platform limit: “Shopify limits each store to one checkout block.” (only affects the checkout placement, which the MVP does not currently expose)
  • Single widget config size cap: 96 KiB (saving fails above this; the editor surfaces a friendly toast)

How do I place a Custom Position widget?

Section titled “How do I place a Custom Position widget?”

Tip: “Open the theme editor and drag the widget to any section.”

Steps:

  1. In the editor’s Display tab, choose “Custom Position”
  2. The editor shows the widget ID, embed code, and an “Add to theme” button
  3. Click “Add to theme” → jumps to the Shopify theme editor
  4. Drag the tt-blocks manual block into the target section
  5. Paste the widget ID in the manual block’s settings panel
  6. Save the theme

Full flow: Custom placement.

Is there a component count limit per widget?

Section titled “Is there a component count limit per widget?”

The component count is bound by the 96 KiB widget config cap. Tens of components is fine in normal use; widgets with very long text or many complex conditions can hit the cap, in which case the editor surfaces a friendly toast.

”Save failed” or “Widget too large” prompt?

Section titled “”Save failed” or “Widget too large” prompt?”

The widget config has a 96 KiB hard cap (D1 metafield 128 KiB raw stack leaves a buffer):

  • Check whether the widget contains very long CSS or many duplicated components
  • Split into multiple widgets (visibility rules can produce the same effect)

My widget colors don’t quite match my theme

Section titled “My widget colors don’t quite match my theme”

Derive colors from your theme: in the creation wizard Step 3 “Color scheme”, pick a bundle from the “From your theme” group.

If you don’t see this group, your theme is not in the supported list (vintage / fully custom themes etc.). See Theme import.