tailwindcss-safe-area/README.md

Tailwind CSS safe area helpers

# tailwindcss-safe-area

Tailwind CSS utilities for safe areas.

## Features

- **Responsive safe area utilities** tailored for margin, padding, height and position
- **Flexible spacing helpers** to extend safe areas or ensure content remains unobstructed with offset and minimum value variants
- **Modern CSS support**, including `inline-start`, `inline-end`, `scroll-margin`, `scroll-padding` and more to handle modern layouts

## Getting started

### For Tailwind CSS v4

```sh
npm install tailwindcss-safe-area
```

Import the CSS plugin directly in your main CSS file:

```css
@import "tailwindcss";
@import "tailwindcss-safe-area";
```

### For Tailwind CSS v3

```sh
# Latest version with v3 support
npm install tailwindcss-safe-area@0.8.0
```

Then add the plugin to your `tailwind.config.js` file:

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

## Usage

To extend content behind the safe area, add or append `viewport-fit=cover` to your viewport meta tag:

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

### Base utilities

Handle safe area margin, padding, height and position:

```html
<header class="pt-safe">...</header>
<main class="px-safe">...</main>
<footer class="pb-safe">...</footer>
```

### Offset utilities

Extend base utilities with an additional offset:

```html
<div class="pr-safe-offset-4">...</div>
```

This adds right padding equal to the safe area plus `4`.

### Or utilities

Apply a minimum value while respecting the safe area:

```html
<div class="pb-safe-or-8">...</div>
```

This adds bottom padding equal to the larger of the safe area or `8`.

## Available utilities

### Margin and padding

**Base utilities:**

- `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`

**With variants:**

- Add `-offset-{value}` for additional spacing (e.g. `pt-safe-offset-4`)
- Add `-or-{value}` for minimum values (e.g. `pb-safe-or-8`)

### Scroll margin and padding

Same as margin/padding utilities, prefixed with `scroll-`:

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

### Height

**Screen height utilities:**

- `h-screen-safe`, `min-h-screen-safe`, `max-h-screen-safe`

**Viewport height variants:**

- `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 utilities:**

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

**With variants:**

- Add `-offset-{value}` for additional spacing (e.g., `top-safe-offset-4`)
- Add `-or-{value}` for minimum values (e.g., `inset-safe-or-8`)