CSS env() Function

The env() function lets you insert user-agent defined environment variables into your CSS.

If you're familiar with the var() function for custom CSS properties, env() works in a very similar way. The big difference is that while you define the values for var() yourself, the values for env() are defined by the browser or the operating system.

The most common use case for the env() function is dealing with "safe areas" on modern mobile devices. Many smartphones and tablets have edge-to-edge screens with physical notches, camera hole-punches, or home indicator bars. The env() function allows you to grab the exact dimensions of these hardware features so you can add padding or margins to prevent your content from being hidden behind them.

Here's a basic example of using env() to apply padding to a container. Note: If you're viewing this on a standard desktop monitor, the box below will likely have zero padding. We'll explain why in the next section.

Fallback Values

The env() function supports fallback values, similar to the var() function. This allows you to provide a default value that will be used if the environment variable is not defined. For example: env(safe-area-inset-top, 20px). If the environment variable is not defined, the browser will use 20px instead.

Here's an example with fallback values:

It's quite possible that you didn't see any padding in this example, which means that the fallback values weren't used. This can happen if the variables do in fact exist, but they're set to zero. If that's the case, then it's actually working as expected.

This can happen on desktop browsers and mobile devices without a notch, where the safe area variables do exist, but are set to 0px. Because 0px is a perfectly valid CSS length, the browser uses it, and your 20px fallback is completely ignored, leaving your element with zero padding (just like in the first example).

So, when does the fallback value actually get used? It only triggers if the environment variable is completely undefined or invalid.

To demonstrate this, we can intentionally misspell the environment variable, or use the wrong case. This will cause the browser to ignore it and trigger the fallback value. Environment variables are case-sensitive. If you misspell the variable or use the wrong capitalization, the browser won't recognize it, and it will trigger your fallback value.

Here's an example demonstrating this by intentionally using the wrong capitalization (safe-area-inset-LEFT):

The "Zero Value" Quirk and the max() Workaround

As discussed, the fallback value won't be used if the environment variable exists but is set to 0px. This causes the padding to be 0px, which is probably not what you want.

To fix this, you can wrap your env() function inside a max() function. This tells the browser: "Use whichever is larger: 20px, or the size of the device notch."

The viewport-fit Requirement

If you want the safe area variables to actually work on mobile devices, there's an important step you must take in your HTML.

By default, mobile browsers will automatically "letterbox" your website to keep it away from the notch. In this default state, the browser sets all safe-area-inset-* variables to 0px. To tell the browser that you want your website to extend into the notch area (so you can handle the padding yourself using env()), you must add viewport-fit=cover to your viewport meta tag in the head of your HTML document:

So the web page will look something like this:

Available Environment Variables

The CSS environment variables specification is expanding to cover more than just mobile notches. Here are the environment variables currently available or in active development at the time of writing:

Safe Area Insets

Used to avoid physical hardware features (like notches) on mobile devices.

• safe-area-inset-top
• safe-area-inset-right
• safe-area-inset-bottom
• safe-area-inset-left

Titlebar Area (Window Controls Overlay)

Used for Progressive Web Apps (PWAs) installed on desktop operating systems. These variables allow you to place web content alongside the native OS minimize/maximize/close buttons.

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

Virtual Keyboard API

Used to get the dimensions of the on-screen virtual keyboard on mobile devices, allowing you to adjust your layout without relying on the browser resizing the entire viewport.

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

Official Syntax

The official syntax of the env() function is as follows:

Possible Values

As indicated in the official syntax, the env() function accepts the following values:

custom-ident

The name of the environment variable you want to use (e.g., safe-area-inset-bottom). This is case-sensitive.

declaration-value

An optional fallback value to use if the environment variable is not set or is invalid. This can be a length, a color, another function, or any other valid CSS value appropriate for the property you're applying it to.

CSS Specifications

• The env() function is defined in CSS Environment Variables Module Level 1 (Editor's Draft)

Browser Support

The following table provided by Caniuse.com shows the level of browser support for this feature.