# 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. ## 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: 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: ``` GET https://help.joy.so/on-site-content/branding/widget-v4.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.