Skip to main content

Device Safe Areas

Overview​

Modern mobile devices, including Android 15 and later, and most iPhones, feature a 'safe-area' insets at the top and bottom of the screen. as plugin frames extend to the very bottom of the screen, they can overlap with this safe-area inset. If not handled correctly, this overlap can lead to user interface issues within your plugins. Buildfire will automatically apply padding to the body of every plugin. In addition, an HTML attribute will be applied to devices that use safe areas. This will be sufficient for most plugins, but not all. To disable the padding, override the padding-bottom of the body tag, using !important.

What are Safe Areas?​

The concept of 'safe areas' emerged with the widespread adoption of edge-to-edge displays on modern smartphones. These displays allow applications to extend content to the very edges of the screen. These spaces are reserved for system functionality; however, apps can still display backgrounds and content behind them.

The decision of whether content should render within or outside of safe areas is contextual. For example, scrolling content can be displayed outside of safe areas, provided that users can scroll the first and last items entirely into view within the safe area. This can be achieved by adding padding to the top and bottom of scrolling containers.

CSS custom variables​

When a device has safe area insets, Buildfire provides CSS custom variables that has the inset value in pixels. Otherwise, their values will be zero.

Use the following variables in your plugin​

--bf-safe-area-inset-top, --bf-safe-area-inset-bottom

Important

Please be aware that the native CSS environment variables safe-area-inset-top and safe-area-inset-bottom are primitive and have known support issues.

To ensure future compatibility, we strongly recommend using the new Buildfire CSS custom variables for handling safe area insets, as detailed in this guide. Failure to update your plugin will result in UI issues on newer devices

Example​

To adjust the position of an element:

.my-class {
  top: calc(5px + var(--bf-safe-area-inset-top));
  bottom: calc(10px + var(--bf-safe-area-inset-bottom));
}

To increase the height of an element:

.my-class {
    height: calc(<original height> + var(--bf-safe-area-inset-top) + var(--bf-safe-area-inset-bottom));
}

Increase the height, using the following CSS:

html[safe-area="true"] .my-class {
  height: calc(<original height> + var(--bf-safe-area-inset-top) + var(--bf-safe-area-inset-bottom));
}

Add padding

html[safe-area="true"] .my-class {
  padding-top: var(--bf-safe-area-inset-top);
  padding-bottom: var(--bf-safe-area-inset-bottom);
}

Additional resources​