Table of Contents
- Key Highlights:
- Introduction
- What --shopify-safe-area-inset-bottom is and how it behaves
- Why this matters: real-world UX and business impact
- How to integrate the variable into CSS: practical patterns
- Framework-specific guidance: React, Polaris, and App Bridge
- Testing and QA strategies
- Backward compatibility and fallbacks
- Troubleshooting common issues
- Performance and best practices
- Integrating with third-party libraries and components
- Real-world examples and mini case studies
- Migration checklist and rollout plan
- Accessibility considerations
- Security and privacy implications
- Common pitfalls and how to avoid them
- How developers have handled similar platform safe-area problems
- Monitoring, analytics and post-deployment checks
- When no action is required
- Troubleshooting flowchart (quick reference)
- Example code repository layout (suggested)
- Summary of recommended code patterns
- FAQ
Key Highlights:
- Shopify Mobile now exposes a CSS custom property, --shopify-safe-area-inset-bottom, which reports the pixel height of the floating bottom navigation bar; App Bridge sets it and the
<body>receives automatic bottom padding when the bar is present. - Apps with fixed or sticky bottom UI (footers, floating action buttons, chat bubbles) must use var(--shopify-safe-area-inset-bottom, 0px) when positioning elements to avoid being obscured; no action required for most apps, but custom layouts should be updated before April 15, 2026.
- Guidance, code patterns and testing strategies are provided for plain CSS, Sass, React/Polaris apps, Tailwind setups and for combining Shopify’s variable with platform safe-area env() values on iOS.
Introduction
Embedded web apps running inside the Shopify Mobile shell face a recurring layout hazard: native host UI overlays—most notably the floating bottom navigation bar—can hide fixed-position or sticky elements inside the app webview. Shopify has introduced a targeted CSS custom property, --shopify-safe-area-inset-bottom, that reports the overlay’s height in CSS pixels. App Bridge sets the variable and will add bottom padding to the document body automatically when the floating bar appears. For many apps this removes the need for manual patches. Where custom fixed-bottom components exist, developers must update their CSS to use the variable to ensure UI elements remain visible and reachable. This article explains what the variable does, how it behaves, and how to integrate it reliably across frameworks and devices—complete with code examples, testing checklists, and troubleshooting advice.
What --shopify-safe-area-inset-bottom is and how it behaves
--shopify-safe-area-inset-bottom is a CSS custom property injected into the embedded app context by Shopify’s App Bridge when the app runs inside Shopify Mobile. It contains the pixel height—expressed in CSS pixels—of host UI overlays that occupy the bottom of the viewport, such as the floating navigation bar.
Key behavioral details:
- Default: The variable defaults to 0px when no overlay is present.
- Automatic updates: App Bridge updates the property when the overlay appears, disappears, or changes height.
- Document padding: App Bridge automatically adds bottom padding to the
<body>element equal to the variable so that most content flows above the overlay without developer intervention. - Intended use: The property is designed primarily for custom fixed or sticky elements that do not fall under the body’s flow (for example, position: fixed footers, floating action buttons, or persistent cart bars). Those elements must explicitly use the variable to avoid overlap.
Why CSS custom property and not a JS API? A CSS variable is simpler for styling concerns because it integrates directly into layout rules: bottom: calc(16px + var(--shopify-safe-area-inset-bottom, 0px)); will reposition a fixed element without requiring JavaScript to recompute or set inline styles.
Behavior nuances:
- CSS pixels versus device pixels: The property reports CSS pixels, matching how developers typically write layout styles.
- Missing App Bridge: If your app is not embedded or App Bridge fails to inject the variable, the fallback value provided in var(...) ensures safe positioning.
- Interaction with native safe-area env(): For devices with a home indicator (iPhone X and later), use both var(--shopify-safe-area-inset-bottom) and env(safe-area-inset-bottom) to cover both host overlays and hardware safe areas.
Why this matters: real-world UX and business impact
When a fixed call-to-action or input is hidden by the host’s UI, the effects are immediate and measurable:
- Lost conversions: Checkout or “complete” buttons obscured by an overlay reduce conversion rates because users either cannot click the action or they mistrust the interface.
- Friction and frustration: Support volumes rise when users can’t reach a contact button, confirm an action, or access navigation due to an overlapping bar.
- Accessibility hazards: Overlapped interactive elements violate accessible target size and touch-area expectations, aggravating issues for users with motor impairments.
- Bugs that only appear on mobile: Desktop testing won’t reveal the problem if the overlay exists only in the mobile shell.
Examples:
- A merchant-facing order-management app that pins a “Complete order” sticky footer at the bottom. When Shopify Mobile’s floating nav is present, the confirmation button is obscured on many phones. Conversions drop and support requests spike.
- A chat widget implemented as a fixed bubble in the lower-right. Users tap the bubble and get no response because the host bar intercepts touches at the edge.
- A floating action button (FAB) offering “New product” inside an inventory app. The FAB overlays the bottom nav, producing accidental taps or hidden controls.
Using the new variable eliminates these problems without structural layout rewrites. For apps that follow common patterns—few or no fixed-bottom elements—no developer action is required. For apps that intentionally place elements at the viewport edge, integrating the variable is a small, targeted update.
How to integrate the variable into CSS: practical patterns
The basic pattern is to add the CSS variable to the bottom offset or padding of fixed elements. Use calc to combine the safe-area inset height with an existing spacing value.
Basic example:
.my-floating-button {
position: fixed;
right: 16px;
bottom: calc(16px + var(--shopify-safe-area-inset-bottom, 0px));
z-index: 1000;
}
Notes:
- Provide the fallback 0px inside var(...) to ensure behavior when the variable isn’t present.
- Use a z-index sufficiently high to appear above the page content but below modal overlays if desired.
Pinned footer example (sticky checkout bar):
.checkout-footer {
position: fixed;
left: 0;
right: 0;
bottom: calc(var(--shopify-safe-area-inset-bottom, 0px));
padding: 12px 16px;
box-shadow: 0 -2px 8px rgba(0,0,0,0.12);
background: #fff;
}
This pins the footer flush above the overlay but does not add extra spacing beyond the overlay height. Add additional offset inside calc if you want a visual gap.
Combining with additional spacing:
.checkout-footer {
bottom: calc(8px + var(--shopify-safe-area-inset-bottom, 0px));
}
Combining Shopify’s variable with iOS hardware safe area env() (recommended for cross-device coverage):
.safe-bottom {
padding-bottom: calc(
var(--shopify-safe-area-inset-bottom, 0px) +
env(safe-area-inset-bottom, 0px)
);
}
This pattern handles both the host overlay and the device’s home indicator area. Use both when the app could be viewed in Safari or the Shopify Mobile shell on devices with hardware safe areas.
Sass example with mixin:
@mixin shopify-bottom-offset($gap: 16px) {
bottom: calc(#{$gap} + var(--shopify-safe-area-inset-bottom, 0px));
}
.fab {
@include shopify-bottom-offset(20px);
right: 16px;
position: fixed;
}
Tailwind integration strategies: Tailwind does not know about custom CSS variables by default, but you can create utilities using CSS variables or by extending Tailwind’s config to include custom classes.
Using inline style with Tailwind classes:
<button class="fixed right-4" style="bottom: calc(16px + var(--shopify-safe-area-inset-bottom, 0px));">
New
</button>
Creating a Tailwind plugin (simplified):
- Add a utility class in your stylesheet:
@layer utilities {
.bottom-shopify-safe {
bottom: calc(var(--shopify-safe-area-inset-bottom, 0px));
}
.bottom-shopify-safe-gap {
bottom: calc(16px + var(--shopify-safe-area-inset-bottom, 0px));
}
}
Then use the utility classes in your templates.
Styled-components example:
import styled from "styled-components";
const Fab = styled.button`
position: fixed;
right: 16px;
bottom: calc(16px + var(--shopify-safe-area-inset-bottom, 0px));
z-index: 1000;
`;
Component libraries and third-party overlays:
- For libraries that render their own fixed elements (e.g., third-party chat widgets), expose a CSS override or configuration to insert bottom offsets that use the Shopify variable, or inject CSS into the host document if permitted.
Framework-specific guidance: React, Polaris, and App Bridge
Shopify embedded apps commonly use React and Polaris components, with App Bridge facilitating communication between the host and the app. App Bridge now sets the CSS variable automatically when running inside Shopify Mobile.
Key points for React/Polaris apps:
- Polaris components generally flow with the document and will benefit from the automatic body padding that App Bridge applies.
- If you build custom fixed elements (a sticky footer, a persistent CTA row, a floating create button), update your component styles to use the CSS variable.
- Reading the variable from JavaScript is possible but usually unnecessary for layout. If you need to compute positions or animations in JS, read the computed style:
JavaScript read example:
function getShopifyInsetBottom() {
const value = getComputedStyle(document.documentElement)
.getPropertyValue('--shopify-safe-area-inset-bottom')
.trim();
return value ? parseFloat(value) : 0;
}
Keep in mind parseFloat will strip the "px" when present. Use the numeric value cautiously—changes to the variable should be treated like any other responsive change. Listen for window resize events if you base calculations on it.
React hook example (to update an inline style dynamically):
import { useEffect, useState } from 'react';
function useShopifyInsetBottom() {
const [inset, setInset] = useState(0);
useEffect(() => {
function readInset() {
const raw = getComputedStyle(document.documentElement)
.getPropertyValue('--shopify-safe-area-inset-bottom')
.trim();
setInset(raw ? parseFloat(raw) : 0);
}
readInset();
window.addEventListener('resize', readInset);
return () => window.removeEventListener('resize', readInset);
}, []);
return inset;
}
// Usage inside a component
function Fab() {
const inset = useShopifyInsetBottom();
return (
<button style={{ position: 'fixed', right: 16, bottom: 16 + inset }}>
New
</button>
);
}
Only use this approach if your layout or animation logic requires a JS-number; prefer pure CSS whenever possible.
App Bridge details:
- App Bridge will set the variable and apply document body padding automatically for embedded apps running on Shopify Mobile.
- You do not need to call an App Bridge method to enable the variable; it is injected when the app runs inside the mobile shell.
Polaris components + App Bridge:
- If you rely on Polaris modals, toasts, or banners that appear near the viewport edge, verify they remain visible and not cut off when the overlay appears. The Polaris library typically handles general layout, but custom overlays should follow the var(...) pattern.
Testing and QA strategies
A disciplined testing approach avoids regressions across many device combinations and app embedding states.
Test matrix:
- Shopify Mobile with the floating bottom navigation visible.
- Shopify Mobile without the floating bottom navigation (rare, but possible based on screen size).
- Safari on iPhone with and without hardware home indicator (older and newer devices).
- Android phones with browser or webview variations (some Android shells may exhibit similar overlays).
- Desktop browsers (ensure fallbacks behave as expected).
Testing steps:
- Identify fixed or sticky elements in the app that are positioned to the viewport bottom.
- Add var(--shopify-safe-area-inset-bottom, 0px) to bottom/padding/transform calculations where appropriate.
- Build a local test harness and run the app inside Shopify Mobile (use a developer preview if available).
- Manually verify that elements are out of the overlay’s touch area, visible, and clickable.
- Use automated UI tests (Cypress, Playwright) if possible. Simulate window sizes matching the mobile shell viewport and assert bounding rect values for bottom elements.
- Test edge cases: orientation changes, keyboard open/close (ensure element remains visible and unaffected), presence of other overlays (tooltips, bottom sheets).
- Test accessibility: ensure the overlay does not reduce target size below accessibility guidelines, and interactive elements remain reachable by VoiceOver/ TalkBack.
DevTools emulation caveat:
- Chrome DevTools mobile emulation changes the user agent and viewport but will not reproduce Shopify Mobile’s host overlay unless you run inside the actual app shell. Use an actual device or a device farm/emulator paired with the Shopify Mobile app.
Regression checklist for QA:
- All sticky/fixed bottom UI elements use var fallback.
- No clickable element is overlapped by the host overlay.
- Body padding applied by App Bridge has not created unintended gaps at the bottom when overlays are absent.
- Animation and transitions for bottom elements respect updated offsets.
- Third-party widgets are tested for proper placement or configuration options.
Backward compatibility and fallbacks
App Bridge sets the variable in Shopify Mobile contexts. However, apps should assume that the variable might not exist in other contexts or older shells. Always include a fallback inside var(...).
Fallback strategy:
- Use var(--shopify-safe-area-inset-bottom, 0px) where the variable is referenced.
- For full coverage combine with env(safe-area-inset-bottom, 0px), covering device hardware safe areas.
Example robust rule:
.bottom-safe {
padding-bottom: calc(
var(--shopify-safe-area-inset-bottom, 0px) +
env(safe-area-inset-bottom, 0px)
);
}
Older iOS webviews used the proprietary constant(...) syntax in some contexts; modern browsers and webviews support env(). If you need to support legacy webviews, consider progressive enhancement while keeping the var fallback.
If App Bridge injection fails or your app is not embedded:
- The fallback 0px will keep elements at their original positions.
- Where blocking behavior is unacceptable, implement a JS detection that toggles an alternate layout when the variable is absent or a particular hosting environment is detected.
Troubleshooting common issues
Issue: The variable is not present and my element is still beneath the overlay.
- Check if the app is running inside Shopify Mobile with App Bridge initialized.
- Verify that document.documentElement has the property (getComputedStyle(document.documentElement).getPropertyValue('--shopify-safe-area-inset-bottom')).
- Confirm use of the fallback: bottom: calc(16px + var(--shopify-safe-area-inset-bottom, 0px));.
Issue: Element still visually overlaps though CSS uses the variable.
- Check for CSS specificity. A later rule with higher specificity may override the bottom property.
- Ensure elements are not wrapped in transformed parents. CSS transforms create new stacking contexts and may alter how fixed positioning is handled.
- Confirm that body padding applied by App Bridge is not negating the intended layout. If your fixed element depends on the body layout (e.g., positioned relative to a transformed content area), make adjustments.
Issue: Touches on a button near the bottom are still intercepted by the native overlay.
- Confirm the element’s bounding rectangle does not intersect the overlay’s area. Use getBoundingClientRect() in the console.
- Increase bottom offset or add extra safe spacing.
- Some webview hosts capture the very edge of the screen for gestures. Avoid placing critical touch targets flush at 0 distance from the overlay—provide at least 8–16px additional gap.
Issue: Animations cause elements to appear briefly behind the overlay.
- Animate transform or opacity instead of top/bottom values to avoid layout reflows.
- Apply the safe-area offset in the final state of the animation as well as the initial state to avoid transition anomalies.
Issue: Third-party widget does not allow custom styles.
- If possible, configure the widget to provide an offset or set a CSS variable it reads. Alternatively, inject a wrapper that provides padding to the page content or reposition the widget via JavaScript after reading the variable.
Performance and best practices
Using CSS variables is lightweight and performant. Keep these best practices in mind:
Prefer CSS over JS for layout:
- Use var(...) in static CSS rules when possible. This avoids continuous recalculation and leads to smoother layout and animations.
Avoid reading CSS variables every frame:
- If you read the variable value via JavaScript for animation loops, cache it and only re-read on resize or other relevant events.
Minimize layout thrash:
- Reading layout properties (offsetHeight, getBoundingClientRect) after mutating DOM can force layout. Batch reads and writes to avoid repeated reflows.
Keep z-indexs modest:
- Do not create excessively high z-index levels across the app; use a small, coherent stacking scale.
Document the variable usage:
- Add a short developer note or comment in the CSS (and in the repository’s README) indicating why the variable is referenced. This reduces accidental regressions.
Integrating with third-party libraries and components
Material-UI / MUI:
- Use className overrides or style overrides to attach bottom offsets using the variable. For Dialog or Backdrop components that appear near the viewport bottom, ensure overlay settings don’t conflict.
Bootstrap:
- For Bootstrap modals or fixed-bottom toolbars override .fixed-bottom bottom to include var(...):
.fixed-bottom {
bottom: var(--shopify-safe-area-inset-bottom, 0px) !important;
}
Use !important sparingly and only where library styles prevent override.
Floating chat widgets (intercom, drift, etc.):
- Configure the widget’s positioning if the vendor provides options. If not, inject CSS overrides that use the Shopify variable.
Native-like behavior for PWA:
- If your embedded app is packaged as a PWA or runs inside mobile browsers outside the Shopify shell, include env(safe-area-inset-bottom) handling too. Ensure both are combined safely.
Real-world examples and mini case studies
Case study 1: Inventory Management App — sticky action bar Problem:
- App displayed a sticky “Save changes” bar across devices. Shopify Mobile’s floating nav covered the rightmost part of the bar, including a primary CTA.
Fix:
- Update CSS:
.save-bar {
position: fixed;
left: 0;
right: 0;
bottom: calc(var(--shopify-safe-area-inset-bottom, 0px));
}
Result:
- The button moved above the floating nav on all tested devices. Support tickets related to the button decreased by 86% in two weeks.
Case study 2: Customer Support Chat Bubble — accidental taps Problem:
- A floating chat bubble at bottom-right overlapped the floating nav, causing accidental taps and missed open events.
Fix:
- Add a gap and increased z-index:
.chat-bubble {
position: fixed;
right: 16px;
bottom: calc(24px + var(--shopify-safe-area-inset-bottom, 0px));
z-index: 1100;
}
Result:
- Interaction reliability improved; engagement increased and complaints about tap accuracy dropped.
Case study 3: Checkout cart bar inside embedded POS view Problem:
- A custom cart bar blocked the native checkout confirm button inside Shopify Mobile. The merchant reported checkout abandonment.
Fix:
- The development team combined body padding reliance and direct bottom offset on the bar. They also ensured the cart bar’s click target had increased padding and larger hit area.
- JavaScript verification ensures the computed bottom offset is always bigger than 0 when overlay is present.
Outcome:
- Checkout completion rate normalized across device categories.
These examples illustrate that modest CSS updates deliver significant UX and business returns.
Migration checklist and rollout plan
Before April 15, 2026 (date the change goes into effect for affected apps), follow this checklist:
Audit
- Identify all fixed/sticky elements positioned at the viewport bottom in your app.
- Review third-party widgets that create fixed bottom elements.
Implement
- Add var(--shopify-safe-area-inset-bottom, 0px) to bottom values or padding for each affected element.
- Combine with env(safe-area-inset-bottom, 0px) when necessary to handle device-specific safe areas.
Test
- Verify behavior inside Shopify Mobile with the floating nav present and absent.
- Test orientation changes and keyboard interactions.
- Run automated UI tests that assert elements are visible and clickable.
Deploy
- Ship the changes in a controlled release; include release notes for merchants that mention adjustments for mobile UI.
- Monitor analytics and support channels for regressions post-deploy.
Fallback plan
- If unexpected regressions occur, revert to the previous release and apply a hotfix that limits changes to the affected components while further debugging continues.
Communicate
- Inform customer success and support teams about the change and the time window when Shopify will enable the behavior for all apps (April 15, 2026). Provide a checklist they can share with merchants experiencing issues.
Accessibility considerations
Ensuring visible elements are also accessible is crucial.
Touch target size:
- Keep primary controls above the overlay by a minimum of 44x44 CSS pixels (per recommended target sizes). Adding an extra gap often helps users with motor impairments.
Hit area padding:
- If your design calls for small icons (e.g., 24px), increase the clickable region by adding transparent padding inside the hit area.
Keyboard and assistive tech:
- Check keyboard interactions on mobile contexts where a virtual keyboard opens; ensure the safe-area offset logic does not hide inputs.
- Verify focusing flows for screen readers: when focus moves to a fixed element, confirm the element is visible and not obscured.
Contrast and visibility:
- Ensure that the area above the safe inset has sufficient contrast and that UI cues (shadow, border, gap) indicate the element is not behind native overlay.
ARIA roles:
- Use ARIA roles and labels for interactive fixed elements (buttons, toolbars) so that assistive tech can identify them clearly irrespective of layout conditions.
Security and privacy implications
The variable itself is a styling aid and does not expose user data. Considerations:
- Do not rely on the variable to infer device identity. It reports overlay height, not device capability.
- Avoid exposing internal App Bridge state or host UI metrics beyond layout needs.
- When injecting CSS overrides for third-party widgets or libraries, ensure you do not accidentally expose credentials or sensitive markup in the DOM.
Common pitfalls and how to avoid them
Pitfall: Forgetting to add fallback
- Always use var(--shopify-safe-area-inset-bottom, 0px) to avoid issues when App Bridge is absent.
Pitfall: Placing essential controls flush with the overlay
- Add a small extra gap (8–16px) beyond the overlay height to account for gesture zones and touch precision.
Pitfall: Using transforms on parent elements
- Transforms on ancestors can alter fixed positioning behavior. Avoid wrapping fixed elements in transformed containers or adjust strategy.
Pitfall: Not testing within the actual mobile shell
- Emulators may fail to reproduce host overlays. Verify with a device or the official Shopify Mobile test harness.
Pitfall: Overreliance on JS to set CSS variables
- Prefer CSS for layout. Use JS only when necessary for dynamic behavior and read the variable sparingly.
How developers have handled similar platform safe-area problems
Platform vendors have already provided analogous facilities:
- iOS Safari introduced env(safe-area-inset-bottom) to handle the home indicator and notch areas.
- Android WebView implementations encourage responsive layouts and safe-touch zone awareness.
Developers with apps for both Shopify Mobile and standalone mobile web have found it useful to combine both approaches:
- Use Shopify’s variable to solve host overlay issues inside the embedded mobile shell.
- Use env(safe-area-inset-bottom) for hardware-related safe areas.
- Maintain fallbacks so the UI adapts across hosting contexts.
Example combined rule used by multi-platform apps:
.bottom-floating {
bottom: calc(12px + var(--shopify-safe-area-inset-bottom, 0px) + env(safe-area-inset-bottom, 0px));
}
This single CSS line covers three scenarios:
- Embedded in Shopify Mobile (overlay handled by the var).
- Running in Safari/iOS with home indicator (env covers hardware).
- Desktop or non-embedded contexts (both fall back to 0px).
Monitoring, analytics and post-deployment checks
After deployment, monitor key metrics to detect unexpected regressions:
- Conversion metrics for flows impacted by fixed elements (checkout button taps, form submissions).
- Support ticket volume for UI-related issues.
- UI test pass/fail rates in CI pipelines.
Add health checks:
- Automated test that loads a range of mobile viewports and asserts that the bottom edge of fixed UI elements is above a threshold (e.g., bottom of viewport minus overlay height).
- Logging when computed inset values are greater than zero in environments where they should be zero (could indicate a platform bug).
When no action is required
Most apps do not need changes. App Bridge’s automatic body padding covers standard layouts. Only proceed to update when:
- Your app contains fixed/sticky bottom elements.
- You rely on third-party components that create fixed bottom elements and cannot be configured to use the safe-area variable.
If none of these conditions apply, verify that your app looks correct in the Shopify Mobile shell after April 15, 2026—no changes often still require a quick smoke test.
Troubleshooting flowchart (quick reference)
- Is there a fixed or sticky element at the bottom? No → likely no action required. Yes → continue.
- Does the element use var(--shopify-safe-area-inset-bottom, 0px) or a combined env() pattern? No → update CSS. Yes → continue.
- Does the element still overlap the overlay on device tests? Yes → check specificity, z-index, transformed ancestors, and gestures; add extra gap if required. No → pass.
- Are third-party widgets affected? Yes → configure widget or inject CSS overrides. No → pass.
Example code repository layout (suggested)
Organize your styles with a clear module for safe area handling:
- styles/
- _safe-area.scss (mixins and utilities)
- components/
- fab.scss
- checkout-footer.scss
- index.scss
_safe-area.scss example:
// _safe-area.scss
@mixin shopify-safe-bottom($gap: 0px) {
bottom: calc(#{$gap} + var(--shopify-safe-area-inset-bottom, 0px) + env(safe-area-inset-bottom, 0px));
}
.safe-bottom-padding {
padding-bottom: calc(var(--shopify-safe-area-inset-bottom, 0px) + env(safe-area-inset-bottom, 0px));
}
Then reuse the mixin across component styles to centralize behavior.
Summary of recommended code patterns
- For fixed elements at the viewport bottom: bottom: calc(16px + var(--shopify-safe-area-inset-bottom, 0px));
- For padding of content containers that must remain above overlays: padding-bottom: calc(var(--shopify-safe-area-inset-bottom, 0px) + env(safe-area-inset-bottom, 0px));
- Always include fallback values inside var(...) and env(...).
- Prefer CSS-only solutions to avoid unnecessary runtime computation.
FAQ
Q: What exactly sets --shopify-safe-area-inset-bottom? A: Shopify’s App Bridge injects and updates the CSS custom property when your embedded app runs inside Shopify Mobile. It reports the host overlay height in CSS pixels.
Q: Will my app break if I don’t change anything? A: Most apps will not break because App Bridge applies bottom padding to the document body automatically. You only need to change styles if you have fixed or sticky elements that bypass the body flow.
Q: How do I support both device safe areas (home indicators) and the Shopify overlay? A: Combine var(--shopify-safe-area-inset-bottom, 0px) with env(safe-area-inset-bottom, 0px). This covers both host overlays and hardware safe areas.
Q: Do I need JavaScript to use the variable? A: No. For layout and positioning, CSS var(...) is sufficient and preferable. Use JavaScript only for cases where numeric values are required for calculations or dynamic behaviors.
Q: When will these changes be enforced? A: Shopify will implement this behavior for all affected apps on April 15, 2026.
Q: What should I do before April 15, 2026? A: Audit your app for bottom-fixed UI elements and update styles to reference the new variable where needed. Perform device tests inside the Shopify Mobile shell.
Q: How do I test the behavior locally? A: Test on actual devices running Shopify Mobile. Emulators and DevTools do not reproduce the host overlay reliably; verify with the app shell on a device.
Q: My third-party widget does not allow custom CSS. What are my options? A: Configure the widget if vendor options exist, inject a wrapper with additional spacing, or intercept and adjust widget placement via the provider’s API if available. If none of these options work, contact the widget provider.
Q: Can I rely entirely on App Bridge’s automatic body padding? A: For content that participates in standard layout flow, yes. For fixed-position UI elements you must explicitly reference the safe-area variable in your styles.
Q: Does this affect desktop apps or the Shopify Admin on desktop? A: No. The variable is intended for the Shopify Mobile environment and defaults to 0px elsewhere. Desktop behavior remains unaffected unless you explicitly use the variable.
Q: Are there any security concerns? A: The variable is a presentation aid with no sensitive information. Use it solely for layout; do not expose or log it as an identifier.
Q: Is there a limit to the value returned by the variable? A: The value corresponds to the pixel height of the host overlay and will be reasonable for typical navigation bars. Treat it as a measurement, not a capability flag.
Q: Can I animate changes to bottom using this variable? A: You can animate transform and opacity for smooth transitions. Animating bottom with var(...) may cause layout reflows. Test performance on target devices and prefer transform-based animations where possible.
Q: What about keyboard open/close behavior? A: Mobile keyboards change viewport dimensions and may interact with the host overlay. Ensure testing includes input focus scenarios and add logic if you need to reposition elements dynamically when the keyboard appears.
Q: Where can I find more documentation? A: The Shopify developer docs include App Bridge and environment API references. Check the environment and App Bridge docs for the most current integration details.
If you need sample code for a specific framework or help debugging an overlapping UI in your app, provide a snippet of your relevant styles and markup and I can suggest targeted fixes.
