CSS env() Function

CSS env() Function

The CSS env() function inserts the value of an environment variable into a CSS declaration, allowing layouts to adapt to device and browser conditions.

Environment variables provide information such as safe screen areas, virtual keyboard dimensions, and window control positions. Unlike CSS custom properties, which are typically defined by the developer, environment variables are commonly supplied by the browser or operating system.

Syntax

env(environment-variable)
env(environment-variable, fallback)

The function accepts an environment variable name and an optional fallback value.

For example:

.header {
  padding-top: env(safe-area-inset-top);
}

This uses the browser-provided top safe area inset as the header's top padding.

Additional examples:

padding-bottom: env(safe-area-inset-bottom);
padding-left: env(safe-area-inset-left, 0px);
bottom: env(keyboard-inset-height, 0px);
width: env(viewport-segment-width 0 0, 100%);
padding-top: calc(20px + env(safe-area-inset-top));

Environment variable names are case-sensitive. Some variables, such as viewport segment variables, also require integer indices.

The value returned by env() must be valid for the CSS property in which it is used.

Parameters

The env() function accepts the following parameters.

For example:

padding-bottom: env(safe-area-inset-bottom, 0px);

If the environment variable is available, its value is used. Otherwise, the fallback of 0px is substituted.

The fallback does not replace an available environment variable whose value happens to be zero.

How It Works

The browser or operating system can provide environment variables describing the current display or application environment.

When the browser calculates a CSS declaration containing env(), it substitutes the corresponding environment value.

For example:

.toolbar {
  padding-bottom: env(safe-area-inset-bottom, 0px);
}

On a rectangular desktop viewport, the safe area inset is normally zero.

On a device with an obstructed or irregular display edge, the browser may provide a positive inset to keep content visible.

Some environment variables can change when the device orientation, viewport, or browser interface changes.

The browser updates the affected CSS values without requiring JavaScript.

Environment Variables

Environment variables are provided by the browser or operating system and can describe different aspects of the display environment.

Not every environment variable is available in every browser or device configuration.

Use fallbacks when a variable is optional or has limited support.

Safe Area Insets

Safe area inset variables identify distances from viewport edges where content might otherwise be obscured by device features.

For example:

.page-content {
  padding-top: env(safe-area-inset-top, 0px);
  padding-right: env(safe-area-inset-right, 0px);
  padding-bottom: env(safe-area-inset-bottom, 0px);
  padding-left: env(safe-area-inset-left, 0px);
}

This allows the page's padding to respond to the current safe area.

On many ordinary desktop displays, all four values are zero.

For mobile pages that need to extend into the full display area, the viewport declaration may include:

<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">

The viewport-fit=cover setting allows supported browsers to extend the layout into areas where safe area padding may be needed.

Maximum Safe Area Insets

The safe-area-max-inset-* variables represent maximum safe area inset values when dynamic browser interface elements are retracted.

They include:

env(safe-area-max-inset-top)
env(safe-area-max-inset-right)
env(safe-area-max-inset-bottom)
env(safe-area-max-inset-left)

Unlike the current safe-area-inset-* values, these maximum values are static for the relevant display configuration.

For example:

.footer {
  padding-bottom: env(safe-area-max-inset-bottom, 0px);
}

This uses the maximum bottom safe area inset when the variable is available.

These variables are useful when a layout needs a stable measurement rather than a value that changes as browser interface elements appear or disappear.

Support for maximum safe area inset variables may be more limited than support for the original safe area variables.

Fallback Values

The optional fallback parameter is used when the requested environment variable is not available.

For example:

.panel {
  padding-left: env(safe-area-inset-left, 20px);
}

If safe-area-inset-left exists and equals 0px, the resulting padding is zero. The 20px fallback is not used.

If the environment variable is unavailable, the fallback value is used.

A fallback can also contain another env() function:

.panel {
  padding-bottom: env(keyboard-inset-height, env(safe-area-inset-bottom, 0px));
}

The browser first looks for the keyboard inset height. If that variable is unavailable, it uses the safe area inset or the final fallback of zero.

If an environment variable is unavailable and no fallback is provided, the declaration can become invalid at computed-value time.

For example:

.panel {
  padding-left: env(unknown-variable);
}

Because no fallback is provided, this declaration cannot supply a valid padding value when the variable is unavailable.

Using env() with calc()

The env() function can be combined with calc() to add environment measurements to ordinary CSS values.

For example:

.header {
  padding-top: calc(16px + env(safe-area-inset-top, 0px));
}

This maintains at least 16 pixels of top padding and adds any additional safe area inset.

Another example:

.bottom-toolbar {
  padding-bottom: calc(12px + env(safe-area-inset-bottom, 0px));
}

The toolbar receives 12 pixels of normal bottom padding plus any required safe area spacing.

Using calc() is useful when an element should retain its regular spacing while adapting to device-specific conditions.

Viewport Segments

Viewport segment variables describe the dimensions and positions of separate viewport regions on supported foldable or multi-screen devices.

Available variable names include:

viewport-segment-width
viewport-segment-height
viewport-segment-top
viewport-segment-right
viewport-segment-bottom
viewport-segment-left

These variables require two integer indices identifying a segment.

For example:

.left-panel {
  width: env(viewport-segment-width 0 0, 50vw);
}
.right-panel {
  width: env(viewport-segment-width 1 0, 50vw);
}

The first index identifies the horizontal segment, and the second identifies the vertical segment.

For a device divided into two side-by-side viewport segments:

• 0 0 identifies the left segment.
• 1 0 identifies the right segment.

For a device divided into two vertically stacked segments:

• 0 0 identifies the top segment.
• 0 1 identifies the bottom segment.

These variables are only defined when the viewport has multiple segments. Ordinary single-screen browsers use the supplied fallback values.

Virtual Keyboard Insets

Virtual keyboard environment variables describe the position and dimensions of an on-screen keyboard in browsers supporting the relevant VirtualKeyboard API behavior.

They include:

keyboard-inset-top
keyboard-inset-right
keyboard-inset-bottom
keyboard-inset-left
keyboard-inset-width
keyboard-inset-height

For example:

.chat-toolbar {
  position: fixed;
  bottom: env(keyboard-inset-height, 0px);
}

In a supported environment where the virtual keyboard overlays page content, this can move a toolbar above the keyboard.

Another example:

.chat-panel {
  padding-bottom: calc(16px + env(keyboard-inset-height, 0px));
}

This adds space for the keyboard when the browser provides a keyboard inset height.

These variables are not universally supported and should not be treated as a complete replacement for responsive viewport handling.

Titlebar Area

Titlebar area environment variables are used by desktop Progressive Web Apps that enable the Window Controls Overlay feature.

They include:

titlebar-area-x
titlebar-area-y
titlebar-area-width
titlebar-area-height

These variables describe the area available for application content near the operating system's window controls.

For example:

.app-titlebar {
  position: fixed;
  left: env(titlebar-area-x, 0px);
  top: env(titlebar-area-y, 0px);
  width: env(titlebar-area-width, 100%);
  height: env(titlebar-area-height, 48px);
}

This positions a custom titlebar using the available area when supported.

The variables are intended for installed desktop applications using the appropriate Window Controls Overlay configuration.

Ordinary browser tabs do not generally provide this environment.

Preferred Text Scale

The preferred-text-scale environment variable represents the user's preferred text scaling factor as determined by the browser or operating system.

For example:

.scaled-text {
  font-size: calc(1rem * env(preferred-text-scale, 1));
}

When supported, this multiplies the base font size by the preferred text scaling factor.

The value is a number rather than a length.

For example, a scaling factor of 1.5 represents 150% of the original size.

Be careful not to apply scaling twice if the browser is already adjusting text sizes automatically.

Relative font sizes such as rem and em remain useful for accessible text sizing even when this environment variable is unavailable.

env() vs. var()

Both functions insert values into CSS declarations, but their values come from different sources.

For example:

:root {
  --base-padding: 16px;
}
.header {
  padding-top: calc(var(--base-padding) + env(safe-area-inset-top, 0px));
}

This combines a developer-defined custom property with a browser-provided environment value.

Example

This example uses env() to add safe area spacing to a content panel while preserving its normal padding.

HTML:

<div class="env-demo">
  <div class="env-demo-panel">
    <h3>Responsive Content Panel</h3>
    <p>This panel uses browser-defined safe area values when available.</p>
  </div>
</div>

CSS:

.env-demo {
  padding: 10px;
  background-color: #f2f5f9;
}
.env-demo-panel {
  padding-top: calc(15px + env(safe-area-inset-top, 0px));
  padding-right: calc(15px + env(safe-area-inset-right, 0px));
  padding-bottom: calc(15px + env(safe-area-inset-bottom, 0px));
  padding-left: calc(15px + env(safe-area-inset-left, 0px));
  background-color: #0066cc;
  color: #fff;
}
.env-demo-panel h3 {
  margin: 0 0 8px;
  color: #fff;
  font-size: 17px;
}
.env-demo-panel p {
  margin: 0;
  color: #fff;
  font-size: 14px;
}

On an ordinary desktop display, the safe area values are usually zero, leaving 15 pixels of padding on each side.

On a device with positive safe area insets, the corresponding padding increases automatically.

Safe Area Example

This example demonstrates a bottom toolbar that adds space for the device's bottom safe area.

HTML:

<div class="env-toolbar-demo">
  <div class="env-toolbar-content">Page Content</div>
  <div class="env-toolbar">
    <span>Home</span>
    <span>Search</span>
    <span>Settings</span>
  </div>
</div>

CSS:

.env-toolbar-demo {
  display: flex;
  flex-direction: column;
  min-height: 180px;
  background-color: #f2f5f9;
}
.env-toolbar-content {
  display: grid;
  flex: 1;
  place-items: center;
  color: #333;
}
.env-toolbar {
  display: flex;
  justify-content: space-around;
  gap: 10px;
  padding: 12px;
  padding-bottom: calc(12px + env(safe-area-inset-bottom, 0px));
  background-color: #0066cc;
  color: #fff;
  font-size: 14px;
}

The toolbar retains 12 pixels of bottom padding and adds the browser's bottom safe area inset when applicable.

For a production mobile layout, apply this technique to a toolbar that actually reaches the viewport edge. The example above demonstrates the CSS calculation within a contained preview.

Common Uses

The env() function is useful for adapting layouts to information provided by the browser or operating system.

For example:

.mobile-footer {
  padding: 16px;
  padding-bottom: calc(16px + env(safe-area-inset-bottom, 0px));
}

This preserves regular spacing while accounting for the bottom safe area.

Limitations

The env() function has several important rules and limitations.

• Environment variable names are case-sensitive.
• Not all environment variables are supported by every browser.
• Some variables are only available in specific device or application configurations.
• Fallback values are used when variables are unavailable, not when their values equal zero.
• Substituted values must be valid for the property receiving them.
• Viewport segment variables require indices to identify the requested segment.
• The function does not directly expose device measurements to JavaScript.
• Environment values can change when the viewport or browser interface changes.
• Browser-defined environment variables should not be confused with ordinary CSS custom properties.

For example, this is valid:

padding-bottom: env(safe-area-inset-bottom, 0px);

The following uses an incorrectly capitalized variable name:

padding-bottom: env(SAFE-AREA-INSET-BOTTOM, 0px);

Because the variable name is case-sensitive, the browser uses the fallback instead of the intended environment value.

The following provides an invalid fallback for a length property:

padding-bottom: env(unknown-variable, red);

If the variable is unavailable, red cannot be used as a padding value, making the declaration invalid at computed-value time.

Browser Support

The CSS env() function is Baseline Widely available. The core function has been supported across major browser engines since January 2020.

It works in current versions of Chrome, Edge, Firefox, Safari, and other modern browsers.

Support for individual environment variables varies. Safe area inset variables are widely supported, while variables for virtual keyboards, foldable devices, titlebar overlays, and preferred text scaling may have more limited support.

For example:

.content {
  padding-bottom: env(safe-area-inset-bottom, 0px);
}

For current compatibility information, visit Can I Use? .

Specifications

The env() function is defined in the CSS Environment Variables Module Level 1 .

The specification defines environment variable substitution, fallback behavior, and browser-provided environment values.

Related CSS features include var(), calc(), CSS custom properties, viewport units, and responsive layout techniques.