CSS env() Beyond Safe Area: Custom Environment Variables

1. What env() is and why it can do more than just safe-area insets

The CSS function env() is known to most developers exclusively through the four safe-area insets that let layouts adapt to the notch, the Dynamic Island or the home indicator bar of modern smartphones. In reality, env() is a general mechanism for so-called environment variables, values that are not set by the author of the stylesheet but supplied by the browser environment itself or by the operating system, and the safe-area insets are only the best known, longest established category of those.

The key conceptual difference from a regular custom property is where the value comes from: a custom property defined with --variable is always set somewhere in your own CSS or through JavaScript, while an environment variable supplies a value the stylesheet itself cannot know or influence, such as the physical cutout of a display. That distinction is more than semantics, it also determines which new environment data might reach CSS through env() instead of a JavaScript API in the future.

2. A quick recap: the four built-in safe-area-inset variables

The four established safe-area insets, safe-area-inset-top, -right, -bottom and -left, each supply the distance a layout should keep from the corresponding edge so content is not obscured by physical display cutouts or system UI elements. They only work inside a document whose viewport meta tag has viewport-fit=cover set, because otherwise the browser already respects the entire safe area automatically and returns the values as constant zero.

These four variables are now broadly supported and a standard building block for PWA and iOS layouts, but they are just one single, very specific use case of the env() function. The actual specification, the CSS Environment Variables Module Level 1, defines the general mechanism far more broadly, and additional environment variables beyond the safe-area insets already exist at various stages of standardization and implementation.

3. Author-defined environment variables: the experimental next step

Beyond the browser's own built-in values, the specification in principle also allows author-defined environment variables that could be introduced through their own registration mechanisms, even though that possibility remains experimental in practice and is currently far from production ready. The underlying idea is that an environment, for example a browser extension framework or a native app shell rendering a web frontend, could supply its own environment values that CSS accesses through the same env() syntax as the built-in safe-area values.

Today, the practically usable path for custom, environment-like values is almost always a regular custom property that JavaScript sets on startup, rather than a genuinely registered environment variable, because browser support for author-defined env() values does not yet exist broadly enough for production projects. Anyone experimenting with it today should treat it explicitly as a forward-looking feature that has to keep working without a fallback at all times.

/* Illustrative only -- author-defined environment variables are not yet
   broadly implemented across engines. Treat this as a forward-looking
   pattern, always paired with a working fallback. */
.app-shell {
  padding-top: env(titlebar-area-height, 0px);
}

4. env() vs. custom properties (var()): where the real difference lies

The practical difference between env() and var() shows up most clearly in the question of who controls the value. A custom property with var(--spacing-lg) is always set somewhere in your own cascade context and is part of the normal inheritance logic, while env() values exist globally, outside the normal cascade and independent of the element they are queried on. An env() value cannot be overridden by a more specific CSS rule the way an inherited custom property could be.

In practice both mechanisms are often combined: the raw value supplied by the environment is queried once through env() and transferred into a project-owned custom property, which is then used, overridden or included in calc() calculations throughout the rest of the stylesheet with ordinary var(). That restores the flexibility of the cascade without losing the original environment value.

:root {
  /* Bridge the raw environment value into a project-owned custom
     property so it can participate in the normal cascade */
  --safe-top: env(safe-area-inset-top, 0px);
  --header-height: calc(3.5rem + var(--safe-top));
}

.app-header {
  padding-top: var(--safe-top);
  height: var(--header-height);
}

5. Use case: viewport segments for foldable devices

A concrete, already partially implemented example of environment variables beyond safe area are the viewport segment variables for foldable devices, which let a layout detect how many segments an unfolded display has and how wide the hinge between them is. These values also arrive through env(), but follow their own, still evolving naming scheme and are so far only available in a handful of browser engines with foldable device support.

The use case illustrates well what env() as a mechanism is fundamentally meant for: making physical properties of the actual display device, which no JavaScript and no server can know in advance, directly available in CSS. Unlike a custom property a developer would have to explicitly set, the browser supplies this device information on its own, as soon as the corresponding device and browser version support it.

/* Foldable device layout: split content across the hinge when
   the browser exposes viewport segment data */
.layout {
  display: grid;
  grid-template-columns:
    env(viewport-segment-width 0 0, 1fr)
    env(viewport-segment-width 1 0, 0px);
  gap: env(viewport-segment-width 0 0, 0px);
}

6. Using fallback values in env() correctly

Every env() function accepts a second, optional parameter as a fallback value, which kicks in whenever the requested environment variable does not exist in the current browser environment. That fallback is not optional in any practical sense with env(), it should fundamentally always be set, because environment variables are inherently device specific and a large share of users will simply never supply them.

A common mistake is setting the fallback only for the four well known safe-area insets and forgetting it for more experimental or newer environment variables, because their lack of support gets tested less often. Without a fallback, the affected CSS declaration is discarded as invalid in non-supporting browsers, which, depending on the property, can lead to a silently missing value or even a completely ignored rule.

.bottom-bar {
  /* Always provide an explicit fallback -- do not assume the
     environment variable exists on every device/browser combination */
  padding-bottom: env(safe-area-inset-bottom, 16px);
  min-height: calc(56px + env(safe-area-inset-bottom, 0px));
}

7. Practical limits: what env() can not (yet) do

Despite its fundamentally open mechanism, env() in practice stays limited to a small, browser-predefined list of variables. Unlike custom properties, which can be freely invented and set at runtime through JavaScript at any time, env() today cannot carry arbitrary application or user state, only values the browser vendor has explicitly implemented as an environment variable.

That boundary is drawn deliberately, because environment variables are conceptually meant to represent properties of the physical or system environment, not arbitrary application data. Anyone wanting to bring their own theme, a user status, or a feature flag decision into CSS therefore remains dependent on regular custom properties set by JavaScript, and should not mistake env() for a generic replacement of that established mechanism.

8. Testing env() values without a real target device

Because physical notch or foldable devices are rarely available on the development machine, Chromium based DevTools offer a device emulation that also simulates env() values for the safe-area insets as soon as a device with a matching cutout is selected in the device dropdown. For values that cannot yet be emulated in DevTools, a direct, temporary test with a fixed value that manually overrides the fallback helps check the layout under realistic conditions.

A simple debugging trick is to temporarily replace the env() call during development with a fixed pixel value matching the expected real-world magnitude, for example 44px for a typical home indicator height, to see how the layout reacts to a non-zero value without needing a real target device. Before shipping, that fixed value must of course be replaced again with the real env() call including its fallback.

/* Temporary debug override -- remove before shipping.
   Simulates a non-zero safe area without a real notch device. */
.app-shell {
  padding-bottom: 44px; /* was: env(safe-area-inset-bottom, 0px) */
}

9. When to use env(), when custom properties: a clear decision guide

The decision between env() and a custom property can be settled with a single question: does the value come from the device's physical or system environment, which neither your own CSS nor your own JavaScript knows about, or is it application state your own project defines and sets itself? In the first case, env() with a sensible fallback is the right choice; in the second case, a regular custom property remains the more direct path.

In practice, for most projects that means: env() today gets used almost exclusively for the four safe-area insets and occasionally for experimental device layouts like viewport segments, while every form of theme, user setting or application logic continues to run through custom properties. That clear separation keeps the stylesheet predictable and makes it obvious at a glance which values come from outside and which the project itself controls.

10. Summary

11. FAQ: CSS env() Beyond Safe Area: The Essentials at a Glance