DOCSEARCHbyAlgolia
Submit Docs

tailwindcss-safe-area

repository·main·Indexed 42 days ago

https://github.com/mvllow/tailwindcss-safe-area

Tailwind CSS safe area helpers providing responsive utilities to handle device safe areas (such as notches and home indicators) using margin, padding, height, and position properties. Supports Tailwind CSS v4 and v3 (v0.8.0), featuring offset and 'or' variants to combine safe area insets with standard Tailwind spacing values.

Tokens
3.6K
Snippets
17
Records
18
Agent score
4%

What's inside tailwindcss-safe-area

  1. Use offset and or variants with safe area utilities

    main

    The plugin provides two powerful modifiers to adjust how safe area spacing is applied:

    1. Offset utilities (-offset-{value}): Adds a specific Tailwind spacing value on top of the safe area value. For example, pr-safe-offset-4 applies right padding equal to the safe area plus the value of 4.
    2. Or utilities (-or-{value}): Applies a minimum value while respecting the safe area. It uses the larger of the safe area or the specified value. For example, pb-safe-or-8 applies bottom padding equal to the larger of the safe area or 8.
    <!-- Offset example: safe area + 4 -->
<div class="pr-safe-offset-4">...</div>

<!-- Or example: max(safe area, 8) -->
<div class="pb-safe-or-8">...</div>

  2. Install tailwindcss-safe-area for Tailwind CSS v3

    main

    To use the plugin with Tailwind CSS v3, install version 0.8.0 and add it to your tailwind.config.js file under the plugins array.

    npm install tailwindcss-safe-area@0.8.0
    // tailwind.config.js
module.exports = {
	theme: {},
	plugins: [require("tailwindcss-safe-area")],
};

  3. Install tailwindcss-safe-area for Tailwind CSS v4

    main

    To use the plugin with Tailwind CSS v4, install the package via npm and import it directly in your main CSS file using @import (instead of @plugin).

    npm install tailwindcss-safe-area
    @import "tailwindcss";
@import "tailwindcss-safe-area";

  4. Configure viewport-fit=cover for safe area support

    main

    To allow content to extend behind the safe areas (enabling the use of these utilities), you must add or append viewport-fit=cover to your viewport meta tag in your HTML.

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

  5. Initialize safe area variables

    main

    To ensure safe area insets are available via CSS variables, use the safe utility. This initializes the following internal variables with the browser's env(safe-area-inset-*) values:

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

    You can apply these in bulk using safe, or target specific axes/sides with safe-x, safe-y, safe-t, safe-r, safe-b, or safe-l.

    <div class="safe">...</div>

  6. Reference: Available safe area utilities

    main

    The plugin provides utilities for margin, padding, height, position, borders, and more. Most utilities support -offset-{value} and -or-{value} variants.

    Margin and Padding

    • m-safe, mx-safe, my-safe, ms-safe, me-safe
    • mt-safe, mr-safe, mb-safe, ml-safe
    • p-safe, px-safe, py-safe, ps-safe, pe-safe
    • pt-safe, pr-safe, pb-safe, pl-safe

    Scroll Margin and Padding

    • scroll-m-safe, scroll-mx-safe, scroll-my-safe, etc.
    • scroll-p-safe, scroll-px-safe, scroll-py-safe, etc.

    Height

    Screen utilities:

    • h-screen-safe, min-h-screen-safe, max-h-screen-safe

    Viewport utilities:

    • h-vh-safe, h-dvh-safe, h-svh-safe, h-lvh-safe
    • min-h-vh-safe, min-h-dvh-safe, min-h-svh-safe, min-h-lvh-safe
    • max-h-vh-safe, max-h-dvh-safe, max-h-svh-safe, max-h-lvh-safe

    -webkit-fill-available utilities:

    • h-fill-safe, min-h-fill-safe, max-h-fill-safe

    Position

    • inset-safe, inset-x-safe, inset-y-safe
    • start-safe, end-safe
    • top-safe, right-safe, bottom-safe, left-safe

    Border

    • border-safe, border-x-safe, border-y-safe
    • border-s-safe, border-e-safe
    • border-t-safe, border-r-safe, border-b-safe, border-l-safe

    Enable/disable safe area

    • safe, safe-x, safe-y
    • safe-t, safe-r, safe-b, safe-l
    • safe-none, safe-x-none, safe-y-none
    • safe-t-none, safe-r-none, safe-b-none, safe-l-none

  7. Use scroll-padding safe area utilities

    main

    The plugin provides two ways to handle scroll-padding to ensure scrolled content stays within safe areas:

    1. Offset Variant (scroll-p-safe-offset-*)

    Adds a specific Tailwind spacing value to the safe area inset. This is useful when you want a fixed amount of extra padding beyond the safe area.

    • scroll-p-safe-offset-*: All sides
    • scroll-px-safe-offset-*: Horizontal
    • scroll-py-safe-offset-*: Vertical
    • scroll-ps-safe-offset-*: Inline start
    • scroll-pe-safe-offset-*: Inline end
    • scroll-pt-safe-offset-*, scroll-pr-safe-offset-*, etc.: Individual sides

    2. Or Variant (scroll-p-safe-or-*)

    Uses the maximum of the safe area inset and a specified Tailwind spacing value. This ensures the padding is at least as large as the safe area, or your specified value, whichever is greater.

    • scroll-p-safe-or-*: All sides
    • scroll-px-safe-or-*: Horizontal
    • scroll-py-safe-or-*: Vertical
    • scroll-ps-safe-or-*: Inline start
    • scroll-pe-safe-or-*: Inline end
    • scroll-pt-safe-or-*, scroll-pr-safe-or-*, etc.: Individual sides

    Negative variants (e.g., -scroll-p-safe-offset-*) are also supported.

    /* Example usage of scroll-padding safe area utilities */
<div class="scroll-p-safe-offset-4">...</div>
<div class="scroll-py-safe-or-2">...</div>

  8. Use inset safe area utilities

    main

    Apply safe area insets to positioning using top, right, bottom, left, or logical start/end properties.

    1. Offset Variant (inset-safe-offset-*)

    Sets the position to the safe area inset plus a specified Tailwind spacing value.

    • inset-safe-offset-*: All sides
    • inset-x-safe-offset-*: Horizontal
    • inset-y-safe-offset-*: Vertical
    • start-safe-offset-*: Inline start
    • end-safe-offset-*: Inline end
    • top-safe-offset-*, right-safe-offset-*, etc.: Individual sides

    2. Or Variant (inset-safe-or-*)

    Sets the position to the maximum of the safe area inset and a specified Tailwind spacing value.

    • inset-safe-or-*: All sides
    • inset-x-safe-or-*: Horizontal
    • inset-y-safe-or-*: Vertical
    • start-safe-or-*: Inline start
    • end-safe-or-*: Inline end
    • top-safe-or-*, right-safe-or-*, etc.: Individual sides

    Negative variants (e.g., -inset-safe-offset-*) are also supported.

    /* Example usage of inset safe area utilities */
<div class="absolute inset-x-safe-offset-4">...</div>
<div class="absolute top-safe-or-2">...</div>

  9. Use border safe area utilities

    main

    Apply safe area insets as border widths.

    1. Base Utilities

    Sets the border width exactly to the safe area inset.

    • border-safe: All sides
    • border-x-safe: Horizontal
    • border-y-safe: Vertical
    • border-s-safe: Inline start
    • border-e-safe: Inline end
    • border-t-safe, border-r-safe, border-b-safe, border-l-safe: Individual sides

    2. Offset Variant (border-safe-offset-*)

    Sets the border width to the safe area inset plus a specified Tailwind spacing value.

    • border-safe-offset-*: All sides
    • border-x-safe-offset-*: Horizontal
    • border-y-safe-offset-*: Vertical
    • border-s-safe-offset-*: Inline start
    • border-e-safe-offset-*: Inline end
    • border-t-safe-offset-*, border-r-safe-offset-*, etc.: Individual sides

    3. Or Variant (border-safe-or-*)

    Sets the border width to the maximum of the safe area inset and a specified Tailwind spacing value.

    • border-safe-or-*: All sides
    • border-x-safe-or-*: Horizontal
    • border-y-safe-or-*: Vertical
    • border-s-safe-or-*: Inline start
    • border-e-safe-or-*: Inline end
    • border-t-safe-or-*, border-r-safe-or-*, etc.: Individual sides
    /* Example usage of border safe area utilities */
<div class="border-t-safe-offset-2">...</div>
<div class="border-x-safe-or-4">...</div>

  10. Use scroll-margin safe area utilities

    main

    The scroll-m-safe-or-* utilities apply scroll-margin values that are the maximum of the device's safe area inset and a specified Tailwind spacing value. This ensures that when scrolling to an element, it respects the safe area but also maintains a minimum margin defined by your design.

    Available utilities include:

    • scroll-m-safe-or-*: All sides
    • scroll-mx-safe-or-*: Horizontal (left/right)
    • scroll-my-safe-or-*: Vertical (top/bottom)
    • scroll-ms-safe-or-*: Inline start
    • scroll-me-safe-or-*: Inline end
    • scroll-mt-safe-or-*: Top
    • scroll-mr-safe-or-*: Right
    • scroll-mb-safe-or-*: Bottom
    • scroll-ml-safe-or-*: Left

    Negative variants (e.g., -scroll-m-safe-or-*) are also available using min() logic.

    /* Example usage of scroll-margin safe area utilities */
<div class="scroll-mt-safe-or-4">...</div>

  11. Apply safe area margins

    main

    Use safe margin utilities to apply safe area insets as margins. These utilities work similarly to standard Tailwind margin classes but use the safe area variables.

    Base Utilities:

    • m-safe: All sides
    • mx-safe: Horizontal (left/right)
    • my-safe: Vertical (top/bottom)
    • ms-safe: Inline start (left)
    • me-safe: Inline end (right)
    • mt-safe, mr-safe, mb-safe, ml-safe: Individual sides

    Negative Margins: Prefix any utility with - (e.g., -m-safe, -mt-safe) to apply negative safe area margins.

    <div class="m-safe">...</div>
<div class="-mt-safe">...</div>

  12. Apply safe area padding

    main

    Use safe padding utilities to apply safe area insets as padding. These utilities work similarly to standard Tailwind padding classes.

    Base Utilities:

    • p-safe: All sides
    • px-safe: Horizontal (left/right)
    • py-safe: Vertical (top/bottom)
    • ps-safe: Inline start (left)
    • pe-safe: Inline end (right)
    • pt-safe, pr-safe, pb-safe, pl-safe: Individual sides

    Negative Padding: Prefix any utility with - (e.g., -p-safe, -pt-safe) to apply negative safe area padding.

    <div class="p-safe">...</div>
<div class="-pl-safe">...</div>