react-tw-breakpointer

v0.1.4

Published

7 months ago

A React component that displays the current Tailwind CSS breakpoint and viewport dimensions

0High
0Medium
0Low

cakemix

react tailwind tailwindcss breakpoint responsive development debugging viewport utility devtools

react-tw-breakpointer

A development utility React component that displays the current Tailwind CSS breakpoint and viewport dimensions in a customizable overlay. Perfect for responsive design development and debugging.

npm version bundle size license

Features

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

Installation

# bun (recommended)
bun add react-tw-breakpointer

# npm
npm install react-tw-breakpointer

# yarn
yarn add react-tw-breakpointer

# pnpm
pnpm add react-tw-breakpointer

Optional: JetBrains Mono Font

For the best visual experience, we recommend installing JetBrains Mono:

bun add @fontsource/jetbrains-mono

Then import it in your app:

// In your app's entry point or layout
import "@fontsource/jetbrains-mono/variable.css";

Quick Start

import { BreakPointer } from "react-tw-breakpointer";

function App() {
  return (
    <>
      {/* Your app content */}
      <BreakPointer />
    </>
  );
}

Usage Examples

Basic Usage

import { BreakPointer } from "react-tw-breakpointer";

function MyApp() {
  return (
    <div>
      {/* Component is automatically hidden in production */}
      <BreakPointer />
    </div>
  );
}

Custom Configuration

<BreakPointer
  initiallyVisible={false}
  toggleKey="b"
  position="top-right"
  zIndex={10000}
  showDimensions={true}
/>

Next.js 15 App Router

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.

Next.js Pages Router

// 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 />
    </>
  );
}

Vite React App

// 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" />
    </>
  );
}

Props

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

Position Options

'bottom-center' (default)
'top-center'
'top-left'
'top-right'
'bottom-left'
'bottom-right'

Breakpoint Reference

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 |

Requirements

React 18 or higher
React DOM 18 or higher
Tailwind CSS 4.0 or higher (for breakpoint visibility classes)

Browser Support

Works in all modern browsers that support:

ES6+
CSS Grid/Flexbox
ResizeObserver API

Performance

Zero runtime dependencies beyond React
< 5KB minified + gzipped
Tree-shakeable - only import what you use
No performance impact in production - component doesn't render

TypeScript

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} />;

FAQ

Why isn't the component showing?

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

Can I use this without Tailwind CSS?

Currently, the component relies on Tailwind's responsive utility classes for breakpoint detection. A non-Tailwind version is planned for a future release.

How do I change the colors?

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.

Does it work with custom Tailwind breakpoints?

The component uses standard Tailwind breakpoints. Support for custom breakpoints is on the roadmap.

How does production hiding work in different frameworks?

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

Roadmap

[ ] 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

Contributing

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

Development

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

License

MIT © ccbbccbb

Acknowledgments

Inspired by development tools that make responsive design easier
JetBrains for the excellent JetBrains Mono font
The Tailwind CSS team for their fantastic framework

Original Inspiration

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 &lt; 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 &lt; 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 &lt; 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 &lt; 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 &lt; 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;

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

react-tw-breakpointer

Features

Installation

Optional: JetBrains Mono Font

Quick Start

Usage Examples

Basic Usage

Custom Configuration

Next.js 15 App Router

Next.js Pages Router

Vite React App

Props

Position Options

Breakpoint Reference

Requirements

Browser Support

Performance

TypeScript

FAQ

Why isn't the component showing?

Can I use this without Tailwind CSS?

How do I change the colors?

Does it work with custom Tailwind breakpoints?

How does production hiding work in different frameworks?

Roadmap

Contributing

Development

License

Acknowledgments

Original Inspiration