@kittler/tailwind-breakpoint-indicator

v1.1.3

Published

8 days ago

Visual breakpoint indicator for Tailwind CSS development

0High
0Medium
0Low

kittler

tailwind tailwindcss breakpoint indicator development dev-tools responsive

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.

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

npm install @kittler/tailwind-breakpoint-indicator

Usage

Where to add the code

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.
HTML – On the page where the helper should run, add a script at the end of <body> that loads this entry file:

<!-- 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:

// 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:

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

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:

Vite: import.meta.env.DEV
Node.js/Webpack: process.env.NODE_ENV === 'development'
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:

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:

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:

<!-- In your HTML -->
<div id="breakpoint-helper"></div>

// 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:

initBreakpointHelper({
  containerSelector: '#my-breakpoint-indicator'
})

Framework Integration

✅ Tested Frameworks

The following frameworks have been tested and verified to work:

Vanilla 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

// main.js (entry file)
import '@kittler/tailwind-breakpoint-indicator/styles'
import '@kittler/tailwind-breakpoint-indicator'

<!-- index.html -->
<script src="/src/main.js" type="module"></script>

Vue

// main.js
import '@kittler/tailwind-breakpoint-indicator/styles'
import '@kittler/tailwind-breakpoint-indicator'

Or in a Vue component:

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

# Install dependencies
npm install

# Build
npm run build

For development and testing instructions, see TESTING.md.

Support

If this tool helps you in your work, you can support its development by buying me a coffee on Ko-fi.

License

MIT