npm package: @kittler/tailwind-breakpoint-indicator
Description: Visual breakpoint indicator for Tailwind CSS development
Latest version: 1.1.3

# Tailwind Breakpoint Indicator

Visual breakpoint indicator tool for Tailwind CSS development. Shows the current active breakpoint in the top-left corner of your browser during development.

![Tailwind Breakpoint Indicator](assets/thumbnail.png)

## Features

- 🎨 Visual indicator with color-coded breakpoints
- 🔄 Automatically detects development mode
- 📐 Auto-detects breakpoints **(limited functionality)**
- ⏱️ Hide button with 20-second auto-show timer
- 🎯 Works with any build tool (Vite, Vue, Webpack, Rollup, etc.)
- 📦 Zero dependencies
- 🎛️ Configurable: customBreakpoints, baseLabel, containerSelector, hideDuration, debug

## Compatibility
Tailwind **v4** is supported and tested. **Tailwind v3 and below have not been officially tested yet.** If you use v3 or older, feedback is welcome.

## Installation

```bash
npm install @kittler/tailwind-breakpoint-indicator
```

## Usage

### Where to add the code

1. **Entry file** – Add the imports to your project’s main entry file (e.g. `src/main.ts`, `src/main.js`, or `src/index.js`). This is the file your bundler (Vite, Webpack, etc.) uses as the entry point.
2. **HTML** – On the page where the helper should run, add a script at the end of `<body>` that loads this entry file:

```html
<!-- At the end of <body> in index.html or your page -->
<script src="/src/main.ts" type="module"></script>
```

With Vite the path is often `/src/main.ts` or similar (e.g. `./src/main.ts`). The `src` attribute must point to your entry file that contains the imports.

### Basic Usage (Auto-initialize)

Import the package in your entry file; in development mode the helper will initialize automatically:

```javascript
// In your entry file (e.g. src/main.ts or src/main.js)
import '@kittler/tailwind-breakpoint-indicator/styles' // Import CSS
import '@kittler/tailwind-breakpoint-indicator' // Import JS (auto-initializes)
```

### Manual Initialization

For more control, you can manually initialize the helper in the same entry file:

```javascript
import '@kittler/tailwind-breakpoint-indicator/styles' // Import CSS
import { initBreakpointHelper } from '@kittler/tailwind-breakpoint-indicator'

// With default options (auto-detects dev mode)
initBreakpointHelper()

// Or with custom options:
// initBreakpointHelper({
//   enabled: true,
//   hideDuration: 30000,
//   containerSelector: '#my-custom-container'
// })
```

### Options

```typescript
interface BreakpointHelperOptions {
  /**
   * When true: show the indicator (e.g. in production or when auto-detect would hide it).
   * When false: indicator is not shown; if it was already created (e.g. by auto-init), it is hidden.
   * When not passed: development mode is auto-detected (Vite, NODE_ENV, localhost).
   * Note: With the auto-import (import '...tailwind-breakpoint-indicator'), the helper inits on load.
   * To keep it off in dev, use manual init only and call initBreakpointHelper({ enabled: false }).
   * @default undefined (auto-detect)
   */
  enabled?: boolean
  /**
   * How long (ms) to hide the indicator when the hide button is clicked. After that, it shows again.
   * @default 20000 (20 seconds)
   */
  hideDuration?: number
  /**
   * CSS selector for an existing element to use as the indicator container. If not set, one is created.
   */
  containerSelector?: string
  /**
   * Custom breakpoints added to the auto-detected set (xs, sm–2xl, 3xl).
   * Required for any other names (4xl, desktop, …). Fallback when CSS detection fails.
   * In Tailwind v3, use for custom screens (xs, 3xl) from theme.extend.screens.
   * @example { xs: '30rem', '3xl': '120rem', desktop: '64rem' }
   */
  customBreakpoints?: Record<string, string>
  /**
   * Label for the range below the first breakpoint. Use false to hide the base row.
   * @default 'base'
   */
  baseLabel?: string | false
  /**
   * Enable debug output in console (CSS detection, breakpoints in use).
   * @default false
   */
  debug?: boolean
}
```

## Development Mode Detection

The helper automatically detects development mode through:

1. **Vite**: `import.meta.env.DEV`
2. **Node.js/Webpack**: `process.env.NODE_ENV === 'development'`
3. **Fallback**: Checks if hostname is `localhost`, `127.0.0.1`, or starts with `192.168.`

You can override this by setting `enabled: true` or `enabled: false` in options.

## Breakpoints

### Auto-detected breakpoints

The tool **automatically recognizes** (from CSS or built-in defaults):

- **xs** – custom (when in CSS, e.g. `--breakpoint-xs` / Tailwind v4 @theme)
- **sm, md, lg, xl, 2xl** – built-in default Tailwind breakpoints
- **3xl** – custom (when in CSS, e.g. `--breakpoint-3xl`)

**Any other names** (4xl, desktop, etc.) **must be defined** via **customBreakpoints**.

- **Tailwind v3:** Built-in sm–2xl work with no config. For custom screens (xs, 3xl) from `theme.extend.screens`, pass them as **customBreakpoints**.
- **Tailwind v4:** Reads from `@theme` when available. If detection fails (e.g. Vue/Vite) or you use extra names, add them with **customBreakpoints**.

Values can be in `px`, `rem`, or `em`.

**customBreakpoints** – Add to the auto-detected set. Use for extra names or as fallback when CSS detection fails:

```javascript
initBreakpointHelper({
  enabled: true,
  customBreakpoints: {
    xs: '30rem',      // v3 custom screen
    '3xl': '120rem',
    '4xl': '160rem',
    desktop: '64rem'
  }
})
```

### Base row

The “base” row is the range below the first breakpoint. You can rename it or hide it:

```javascript
initBreakpointHelper({
  baseLabel: 'default',  // show as "default" instead of "base"
  // baseLabel: false,    // hide the base row; only breakpoint names are shown
})
```

## Using Existing HTML Element

If you prefer to use your own HTML element (e.g., from a template), you can:

```html
<!-- In your HTML -->
<div id="breakpoint-helper"></div>
```

```javascript
// In your JS - the helper will use the existing element
import '@kittler/tailwind-breakpoint-indicator/styles'
import { initBreakpointHelper } from '@kittler/tailwind-breakpoint-indicator'

initBreakpointHelper()
```

Or use a custom selector:

```javascript
initBreakpointHelper({
  containerSelector: '#my-breakpoint-indicator'
})
```

## Framework Integration

### ✅ Tested Frameworks

The following frameworks have been tested and verified to work:

#### Vanilla HTML

```html
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="path/to/styles.css">
</head>
<body>
  <script type="module">
    import '@kittler/tailwind-breakpoint-indicator/styles'
    import '@kittler/tailwind-breakpoint-indicator'
  </script>
</body>
</html>
```

#### Vanilla HTML + Vite

```javascript
// main.js (entry file)
import '@kittler/tailwind-breakpoint-indicator/styles'
import '@kittler/tailwind-breakpoint-indicator'
```

```html
<!-- index.html -->
<script src="/src/main.js" type="module"></script>
```

#### Vue

```javascript
// main.js
import '@kittler/tailwind-breakpoint-indicator/styles'
import '@kittler/tailwind-breakpoint-indicator'
```

Or in a Vue component:

```vue
<script setup>
import { onMounted } from 'vue'
import { initBreakpointHelper } from '@kittler/tailwind-breakpoint-indicator'
import '@kittler/tailwind-breakpoint-indicator/styles'

onMounted(() => {
  initBreakpointHelper()
})
</script>
```

### ⚠️ Other Frameworks

The following frameworks should work but have not been tested yet. If you test them, please report any issues:

- **React** - Should work with `useEffect` hook
- **Svelte** - Should work with `onMount` lifecycle
- **Angular** - Should work in component lifecycle hooks
- **Webpack** - Should work with standard imports
- **Rollup** - Should work with standard imports

## Building from Source

If you want to build the package from source:

```bash
# Install dependencies
npm install

# Build
npm run build
```

For development and testing instructions, see [TESTING.md](./TESTING.md).

## Support

If this tool helps you in your work, you can support its development by buying me a coffee on [Ko-fi](https://ko-fi.com/jakubkittler).

## License

MIT