Visual breakpoint indicator for Tailwind CSS development
npm install @kittler/tailwind-breakpoint-indicatorbash
npm install @kittler/tailwind-breakpoint-indicator
`
Usage
$3
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 that loads this entry file:
`html
`
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.
$3
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)
`
$3
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'
// })
`
$3
`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
/**
* 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
$3
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'
}
})
`
$3
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
`
`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
$3
The following frameworks have been tested and verified to work:
#### Vanilla HTML
`html
`
#### Vanilla HTML + Vite
`javascript
// main.js (entry file)
import '@kittler/tailwind-breakpoint-indicator/styles'
import '@kittler/tailwind-breakpoint-indicator'
`
`html
`
#### Vue
`javascript
// main.js
import '@kittler/tailwind-breakpoint-indicator/styles'
import '@kittler/tailwind-breakpoint-indicator'
`
Or in a Vue component:
`vue
`
$3
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
``