Change the widget player z-index

📘

One-line summary

You can change the display priority of the JOIN widget (above or below other elements on your site) by setting a few CSS variables, without changing widget code.

Overview

z-index controls which element appears in front of others.

If your widget appears behind a cookie banner, chat, sticky menu, or modal, you can adjust this behavior with JOIN CSS variables.

In most cases, you only need to add a small CSS block to your site (in your stylesheet, theme, or tag manager).

Which setting for which case

How it works

1. Choose the behavior you want

Decide whether you want the widget to appear:

• above other site elements (higher value),
• or below them (lower value).

2. Add CSS variables

You can define variables globally (for the entire site):

:root {
    --join-container-index: 9999;
    --join-sticky-widget-z-index: 9998;
    --join-sticky-widget-player-z-index: 9999;
    --join-spotlight-widget-z-index: 9998;
}

Or with a minimal setup (standard player only):

:root {
    --join-container-index: 1500;
}

3. Validate real-world rendering

Test at least:

• a page with a cookie banner,
• a page with chat/support,
• desktop + mobile.

Targeted option (specific area only)

If you do not want to impact the whole site, define variables only in a specific section.

.product-page {
    --join-container-index: 1200;
    --join-sticky-widget-player-z-index: 1201;
}

In this example, changes apply only inside .product-page.

Ready-to-use examples

Example A: Keep cookie banner above the player

:root {
    --join-container-index: 1300;
}

/* Example only: your cookie banner value may differ */
.cookie-banner {
    z-index: 1400;
}

Example B: Ensure widget is above a sticky header

.site-header {
    z-index: 1100;
}

:root {
    --join-container-index: 1200;
    --join-sticky-widget-z-index: 1200;
    --join-sticky-widget-player-z-index: 1201;
}

Example C: Page-specific override (product pages only)

.template-product {
    --join-container-index: 2000;
    --join-sticky-widget-z-index: 1999;
    --join-sticky-widget-player-z-index: 2000;
}

Example D: Inline <style> in your page/template

<style>
    :root {
        --join-container-index: 1600;
        --join-spotlight-widget-z-index: 1600;
    }
</style>

Recommended values

• 1200 to 1999: good level to stay above regular content.
• 2000 to 4999: useful if you already have high sticky headers or menus.
• 9000+: use only if you have very high-priority third-party overlays.

Practical tip: increase values step by step, then test again.

Rules and limits

• z-index only works on positioned elements (already handled by the widget).
• If another component uses a higher value, it will stay in front.
• A value that is too high may place the widget above important popups (consent, payment, security).
• For solo-sticky widgets, the closed trigger and open player can use different values.

Validation checklist

• The widget is visible on page load.
• Opening the player works without going behind another overlay.
• Closing the player stays clickable.
• The cookie banner remains visible if your policy requires it.
• Support chat remains usable.
• Behavior is correct on both mobile and desktop.

FAQ

• Q: Which variable should I change first?
  Start with --join-container-index for the standard player. If you use solo-sticky mode, also adjust --join-sticky-widget-z-index and --join-sticky-widget-player-z-index.

• Q: Do I need a very large value?
  Not necessarily. Start with a moderate value (for example: 1200), then increase only if needed.

• Q: Can I apply this only on specific pages?
  Yes. Set CSS variables on a specific page container instead of :root.

• Q: The widget is still behind my chat. What should I do?
  Increase the relevant variable in small steps and compare it with the chat z-index. Keep the lowest value that works.

• Q: Can these changes break the widget?
  No. You only change visual stacking order. Widget behavior stays the same.

• Q: Are these variables blocked by Shadow DOM?
  No. JOIN uses CSS custom properties for these z-index values, and custom properties are inherited into the shadow tree from the host/page context.

Quick technical reference

Supported variables:

• --join-container-index
• --join-sticky-widget-z-index
• --join-sticky-widget-player-z-index
• --join-spotlight-widget-z-index

Internal default values (if not set):

• --join-container-index: 2147483647
• --join-sticky-widget-z-index: 2147483647
• --join-sticky-widget-player-z-index: 2147483646
• --join-spotlight-widget-z-index: 999999999