A lightweight dev util made for Tailwind CSS + Next.js/React. It displays the current Tailwind CSS breakpoint at the bottom of the screen as well as viewport dimensions in a customizable overlay. Perfect for responsive design development and debugging.
- Live Breakpoint Display - Shows current Tailwind breakpoint (xs, sm, md, lg, xl, 2xl)
- Viewport Dimensions - Displays real-time width and height
- Color-Coded Indicators - Each breakpoint has a unique color for quick identification
- Keyboard Toggle - Visible by default; press 't' to turn on and 'Shift+T' to turn off (configurable)
- Client-only - Import from a Client Component in App Router; resolves to a no-op on the server
- No Tailwind Dependency - Ships its own lightweight CSS; no safelist or node_modules scan needed
- Zero Dependencies - Only requires React as a peer dependency
- Highly Configurable - Customize position, visibility, font, and more
- TypeScript Support - Full type definitions included
- SSR Safe - Works with Next.js and other SSR frameworks
# bun (recommended)
bun add react-tw-breakpointer
# npm
npm install react-tw-breakpointer
# yarn
yarn add react-tw-breakpointer
# pnpm
pnpm add react-tw-breakpointerFor the best visual experience, we recommend installing JetBrains Mono:
bun add @fontsource/jetbrains-monoThen import it in your app:
// In your app's entry point or layout
import "@fontsource/jetbrains-mono/variable.css";import { BreakPointer } from "react-tw-breakpointer";
function App() {
return (
<>
{/* Your app content */}
<BreakPointer />
</>
);
}import { BreakPointer } from "react-tw-breakpointer";
function MyApp() {
return (
<div>
{/* Component is automatically hidden in production */}
<BreakPointer />
</div>
);
}<BreakPointer
initiallyVisible={false}
toggleKey="b"
position="top-right"
zIndex={10000}
showDimensions={true}
/>In App Router, render the component inside a Client Component. Importing from a Server Component resolves to a no-op by design.
Option A: Use an existing Client Component (recommended)
// app/providers.tsx
'use client';
import { BreakPointer } from 'react-tw-breakpointer';
export function Providers({ children }: { children: React.ReactNode }) {
return (
<>
{children}
<BreakPointer />
</>
);
}Then include <Providers> in app/layout.tsx.
Option B: Minimal client wrapper if you don't have one yet
// app/components/BreakPointerClient.tsx
'use client';
import { BreakPointer } from 'react-tw-breakpointer';
export function BreakPointerClient() {
return <BreakPointer />;
}// app/layout.tsx (server component)
import type { ReactNode } from 'react';
import { BreakPointerClient } from './components/BreakPointerClient';
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html lang="en">
<body>
{children}
<BreakPointerClient />
</body>
</html>
);
}Behavior:
- The component renders on the client whenever used from a Client Component.
- On the server, it resolves to a no-op (to avoid RSC hook errors).
- Uses an injected, namespaced stylesheet (
rtwbp-*), independent of your Tailwind config.
// pages/_app.tsx
import "@fontsource/jetbrains-mono/variable.css";
import { BreakPointer } from "react-tw-breakpointer";
import type { AppProps } from "next/app";
export default function MyApp({ Component, pageProps }: AppProps) {
return (
<>
<Component {...pageProps} />
<BreakPointer />
</>
);
}// main.tsx or App.tsx
import "@fontsource/jetbrains-mono/variable.css";
import { BreakPointer } from "react-tw-breakpointer";
function App() {
return (
<>
{/* Your app */}
<BreakPointer position="bottom-left" />
</>
);
}| Prop | Type | Default | Description |
|---|---|---|---|
initiallyVisible |
boolean |
true |
Whether the component is visible on mount |
toggleKey |
string |
deprecated |
Deprecated; use toggleOnKey/toggleOffKey |
toggleOnKey |
string |
't' |
Keyboard key to turn the overlay on |
toggleOffKey |
string |
'T' |
Keyboard key to turn the overlay off |
position |
Position |
'bottom-center' |
Position of the overlay on screen |
zIndex |
number |
9999 |
z-index of the overlay |
hideInProduction |
boolean |
removed |
Removed; component no longer auto-hides in prod |
screens |
{ sm?, md?, lg?, xl?, '2xl'? } |
Tailwind defaults | Override breakpoint thresholds (px) |
showDimensions |
boolean |
true |
Show viewport width and height |
className |
string |
undefined |
Additional CSS classes |
style |
React.CSSProperties |
undefined |
Additional inline styles |
fontFamily |
string |
JetBrains Mono stack | Custom font family |
'bottom-center'(default)'top-center''top-left''top-right''bottom-left''bottom-right'
The component displays the following Tailwind CSS breakpoints:
| Breakpoint | Min Width | Color | Label |
|---|---|---|---|
| xs | 0px | Red (#ec2427) | 1/6 " xs |
| sm | 640px | Orange (#f36525) | 2/6 " sm |
| md | 768px | Yellow (#edb41f) | 3/6 " md |
| lg | 1024px | Light Yellow (#f7ee49) | 4/6 " lg |
| xl | 1280px | Blue (#4686c5) | 5/6 " xl |
| 2xl | 1536px | Green (#45b64a) | 6/6 " 2xl |
- React 18 or higher
- React DOM 18 or higher
- Tailwind CSS 4.0 or higher (for breakpoint visibility classes)
Works in all modern browsers that support:
- ES6+
- CSS Grid/Flexbox
- ResizeObserver API
- Zero runtime dependencies beyond React
- < 5KB minified + gzipped
- Tree-shakeable - only import what you use
- No performance impact in production - component doesn't render
Full TypeScript support with exported types:
import { BreakPointer, BreakPointerProps } from "react-tw-breakpointer";
const config: BreakPointerProps = {
position: "top-right",
toggleKey: "b",
zIndex: 10000,
};
<BreakPointer {...config} />;- Ensure it's rendered from a Client Component (App Router server files resolve to a no-op)
- Try pressing the default keys: 't' turns on, 'Shift+T' turns off
- Check for overlapping overlays or z-index conflicts
- If you customized
screens, verify the values match your expected breakpoints
Currently, the component relies on Tailwind's responsive utility classes for breakpoint detection. A non-Tailwind version is planned for a future release.
You can override the colors using the className or style props, though this may affect the breakpoint visibility logic. Custom color schemes are planned for v2.
The component uses standard Tailwind breakpoints. Support for custom breakpoints is on the roadmap.
- Next.js App Router: The component is conditionally rendered server-side, so it's never sent to production clients
- Next.js Pages Router: The component renders on the client but returns null in production
- Vite/CRA: The component renders on the client but returns null in production
- Server Components: Use
process.env.NODE_ENV === "development"for optimal performance
- Support for custom breakpoints
- Non-Tailwind CSS version
- Custom color schemes
- Draggable positioning
- Keyboard shortcuts for position changes
- Display orientation info
- Pixel density display
- Save preferences to localStorage
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Install dependencies (
bun install) - Make your changes
- Run tests and linting (
bun run check) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
# Install dependencies
bun install
# Run development build with watch mode
bun run dev
# Build for production
bun run build
# Type check
bun run type-check
# Lint and format
bun run lint
# Check all (types, lint, format)
bun run check
# Dry run publish
bun run publish:dryMIT © ccbbccbb
- Inspired by development tools that make responsive design easier
- JetBrains for the excellent JetBrains Mono font
- The Tailwind CSS team for their fantastic framework
This package was inspired by and based on the following original component I created for my own use:
import React, { useEffect, useState } from "react";
const BreakPointer = () => {
const [isVisible, setIsVisible] = useState(true);
const [viewport, setViewport] = useState({
width: 0,
height: 0,
});
useEffect(() => {
const updateViewport = () => {
setViewport({
width: window.innerWidth,
height: window.innerHeight,
});
};
const handleKeyPress = (event: KeyboardEvent) => {
if (event.key === "y" || event.key === "Y") {
setIsVisible((prev) => !prev);
}
};
updateViewport();
document.addEventListener("keydown", handleKeyPress);
window.addEventListener("resize", updateViewport);
return () => {
document.removeEventListener("keydown", handleKeyPress);
window.removeEventListener("resize", updateViewport);
};
}, []);
if (process.env.NODE_ENV === "production") return null;
if (!isVisible) return null;
return (
<div className="fixed bottom-2 left-1/2 z-[9999] -translate-x-1/2 rounded border-2 border-black text-xs">
<span className="block items-center bg-[#ec2427] px-2 py-1 font-mono font-semibold tracking-tighter text-white sm:hidden md:hidden lg:hidden xl:hidden 2xl:hidden">
1/6 • xs • {viewport.width}px < 640px
</span>
<span className="hidden items-center bg-[#f36525] px-2 py-1 font-mono font-semibold tracking-tighter text-white sm:block md:hidden lg:hidden xl:hidden 2xl:hidden">
2/6 • sm • {viewport.width}px < 768px
</span>
<span className="hidden items-center bg-[#edb41f] px-2 py-1 font-mono font-semibold tracking-tighter text-white md:block lg:hidden xl:hidden 2xl:hidden">
3/6 • md • {viewport.width}px < 1024px
</span>
<span className="hidden items-center bg-[#f7ee49] px-2 py-1 font-mono font-semibold tracking-tighter text-black lg:block xl:hidden 2xl:hidden">
4/6 • lg • {viewport.width}px < 1280px
</span>
<span className="hidden items-center bg-[#4686c5] px-2 py-1 font-mono font-semibold tracking-tighter text-white xl:block 2xl:hidden">
5/6 • xl • {viewport.width}px < 1536px
</span>
<span className="hidden items-center bg-[#45b64a] px-2 py-1 font-mono font-semibold tracking-tighter text-white 2xl:block">
6/6 • 2xl • {viewport.width}px ≥ 1536px
</span>
</div>
);
};
export default BreakPointer;