> For the complete documentation index, see [llms.txt](https://help.joy.so/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.joy.so/on-site-content/branding/widget-v4.md). # Unified Widget — New Storefront UI {% hint style="info" %} **Who can use this feature?** * Available on all plans * **New stores** installed after the Unified Widget release date run on it by default — no setup needed. * **Existing stores** stay on the legacy widget (V3) until you request the upgrade through our support team. {% endhint %} ## Overview The **Unified Widget** is a complete rebuild of Joy's storefront experience — the floating widget, loyalty page, account page, cart drawer redeem, and points calculator — on **Lit Web Components**. **Why "Unified"?** Until now, each storefront surface was its own piece of code with its own styling rules. The Unified Widget brings all of them onto **one codebase, one component library, and one shared design-token system**. Style it once and every surface — widget, loyalty page, account page, cart drawer, calculator — stays consistent. No patchwork, no surface that "looks a bit different." What you get: * **Unrestricted theming** — every color, font, radius, and spacing exposed as a CSS custom property. Match your brand pixel-for-pixel without custom CSS battles. * **Modular blocks** — 39 reusable components ("Lego-block" architecture). Compose your loyalty page the way you compose a Shopify section. * **Faster, lighter** — props-driven components, lazy-loaded chunks, smaller bundle on first paint. * **Zero-risk migration** — your existing settings, programs, points, and customers stay untouched. The Unified Widget reuses your current business logic; only the visual layer changes. > Same Joy. Same data. New aesthetic command center. {% embed url="" %} ## Before you start * The Unified Widget is rolled out store-by-store. Your legacy widget keeps running until the Unified Widget is enabled on your store. * Both versions won't load at the same time — Joy dynamically loads only the one your store has enabled. * Some legacy-only features stay on the old widget until they migrate (Milestone program UI, interactive website popup, Wallet pass / QR, Submit receipt program, branded reminder popup). Joy auto-falls back to the legacy widget for these flows. ## How to get the Unified Widget ### New stores If you installed Joy after the Unified Widget release, you're already on it — no setup needed. Open your loyalty page or storefront widget to see the new design. ### Existing stores If you've been on the legacy widget, request the upgrade through our support team. We'll enable the Unified Widget on your store and your existing branding, programs, points, and customers transfer automatically: * **In-app:** open the support chat from your Joy dashboard * **Email:** — subject "Enable Unified Widget" * **Help center:** [help.joy.so](https://help.joy.so) → contact form After we enable it, customize the new design in **On-site content → Branding → Widget Design** using the design token editor: * **Colors** — primary, secondary, surface, on-surface, accent (with auto-contrast pairs) * **Typography** — font family, size scale, weight, letter-spacing * **Shape** — border radius scale (button, card, modal) * **Spacing** — padding/gap scale across all blocks * **Custom CSS** — still supported, now scoped via CSS custom properties
Unified Widget Design tab with Preset themes, Industry inspiration, and Style controls

Unified Widget design editor — pick a preset, an industry inspiration, or fine-tune every token by hand.

### Want to roll back? Reach out to support the same way and we'll switch your store back to the legacy widget. ## Customize the Unified Widget Open **On-site content → Branding → Widget Design** to fine-tune the new surface. Recent additions: ### Preview with your storefront fonts In the editor's **Preview settings**, enter your **Storefront URL** and click **Load fonts** so the "Inherit" font renders accurately while you design. If your storefront is password-protected, add the **Storefront password** (used once for this preview, never stored). Your live storefront is unaffected.
Preview settings — Load storefront fonts

Load your theme fonts so the preview matches your live store.

### Floating drawer layout Under **Design → Layout**, pick **Floating drawer** — a drawer with rounded corners and a margin from the screen edges for a softer, floating look. Set the **Floating margin** (8–32px). On mobile it still stacks into a bottom sheet like the standard drawer.
Floating drawer layout option in Design → Layout

The new Floating drawer layout, inset from the viewport edges.

### Always show the tier progress bar In **Membership card** settings, turn on **Always show tier progress bar** to surface the next-tier progress bar without customers expanding the tier section. Works for both **Compact** and **Classic** card layouts.
Always show tier progress bar toggle and storefront result

The next-tier progress bar stays visible on the membership card.

### More editor improvements * **Welcome greeting variables** — use `{customer_name}`, `{customer_firstname}`, or `{customer_lastname}` in the **Welcome back greeting**. Specific-name variables override the "Customer name display" setting. * **Per-program detail image** — give each earning/redeeming program a separate hero image for its detail view, on top of the small list icon. * **Recommended cold-start fallback** — choose which browsing signal personalizes recommendations (**Personalize from**) and a **Fallback collection** shown when no signal matches. * **Province / State field** — the address form now collects province, state, or prefecture (e.g. Japan), so saving an address no longer clears it. * **Page transition** — animate view changes with **None**, **Slide**, or **Fade** (Design → Layout). ## What changes for your customers | Surface | Legacy widget (V3) | Unified Widget | | ------------------------------------ | -------------------- | --------------------------------------------------------------------------------------------------------- | | Floating widget (FAB + drawer/popup) | Preact, fixed layout | Web Component, customizable layout | | Loyalty landing page | Single template | 10 modular blocks (Hero, How it Works, Ways to Earn, Ways to Redeem, VIP, Referral, Activity, FAQs, etc.) | | Account page | Plain HTML | 4 dedicated blocks (points, tier, activity, redeem) | | Cart drawer redeem | Static button | `` web component, theme-aware | | Points calculator | Inline DOM | `` web component, variant-aware | ## Frequently asked questions ### Will this break my current widget? No. Your legacy widget keeps running until our team enables the Unified Widget on your store. ### Do I need to redo my branding settings? No. Your current colors, fonts, and button styles auto-map to the Unified Widget's design tokens when it's enabled. You can fine-tune from there. ### What happens to features not yet migrated? Milestone program UI, interactive website popup, Wallet pass / QR, Submit receipt program, and branded reminder popup remain on the legacy widget. Joy auto-falls back when the customer hits one of those flows — no broken UI. ### Can I roll back? Yes. Contact support and we'll switch your store back to the legacy widget. ### Does the Unified Widget affect Shopify Flow, Klaviyo, or other integrations? No. It only changes the storefront view layer. All triggers, events, API endpoints, and webhook payloads remain identical. ### When will the remaining features migrate? Tracked on the [Roadmap](/product-roadmap/joy-loyaltys-roadmap.md). Subscribe to the changelog to get notified. ## Need help? Reach out at with your store URL and "Unified Widget" in the subject — we'll handle enable, rollback, and any setup questions. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.joy.so/on-site-content/branding/widget-v4.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.