Breakpointer

A lightweight React library for real-time breakpoint detection with support for custom and default Tailwind breakpoints.

Breakpointer in action:

Installation

npm install breakpointer

Exports

| Export | Description | |--------|-------------| | BreakpointerProvider | A context provider to wrap your application | | useBreakpointer | A hook to access the current breakpoint |

Basic Usage

Setup

Wrap your application with BreakpointerProvider:

import React, { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';
import { BreakpointerProvider } from 'breakpointer';

/* 
    if mode !== "development", the BreakpointerIndicator will skip rendering   
*/
const MODE = import.meta.env.MODE; // based on your chosen build tool

createRoot(document.getElementById('root')!).render(
    <StrictMode>
        <BreakpointerProvider mode={MODE}>
            <App />
        </BreakpointerProvider>
    </StrictMode>,
)

Using the Hook

Use the useBreakpointer hook to detect breakpoints in your components:

import React from 'react';
import { useBreakpointer } from 'breakpointer';

const MyComponent = () => {
    const {
        screen,      // ex: "md" if currentWidth is in the range from 768 - 1023
        currentWidth // innerWidth/viewPort width
    } = useBreakpointer();
    
    return (
        <div>
            {screen === 'sm' && <p>Small screen (640px - 767px)</p>}
            {screen === 'md' && <p>Medium screen (768px - 1023px)</p>}
            {screen === 'lg' && <p>Large screen (1024px - 1279px)</p>}
            <p>Current width: {currentWidth}px</p>
        </div>
    );
};

export default MyComponent;

Default Breakpoints

Breakpointer comes with the following default breakpoints, which align with Tailwind CSS's default breakpoint system:

| Breakpoint | Min Width (px) | Description | |------------|----------------|--------------------------------------| | sm | 640 | Large phones & small tablets | | md | 768 | Tablets | | lg | 1024 | Laptops & large tablets | | xl | 1280 | Desktop & large laptops | | 2xl | 1536 | Wide screen & large desktops |

Usage with Tailwind v3

Note: resolveConfig is only applicable for Tailwind CSS version 3.x.x.

To use custom Tailwind breakpoints, pass a breakpointsObj prop to BreakpointerProvider:

import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';
import { BreakpointerProvider } from 'breakpointer';

import resolveConfig from "tailwindcss/resolveConfig"; // resolver Function
import tailwindConfig from "../tailwind.config"; // js/ts tailwind config 

const resolvedConfig = resolveConfig(tailwindConfig);

createRoot(document.getElementById('root')!).render(
    <BreakpointerProvider breakpointsObj={resolvedConfig.theme.screens}>
        <App />
    </BreakpointerProvider>,
    document.getElementById('root')
);

BreakpointerIndicator

The BreakpointerIndicator component has been integrated into the BreakpointerProvider, so there is no need for manual invocation. You can now customize its appearance by passing a classNames object as a prop to the BreakpointerProvider.

classNames Object

The classNames object allows you to style the internal elements of the BreakpointerIndicator. Below is a table describing the available properties:

| Property | Description | |----------------|-----------------------------------------------------------------------------| | wrapper | Styles the outer wrapper of the indicator. | | iconWrapper | Styles the container for the breakpoint icon. | | screen | Styles the text displaying the current breakpoint (e.g., sm, md). | | currentWidth | Styles the text displaying the current viewport width in pixels. |

Example Usage

import { BreakpointerProvider } from 'breakpointer';

const App = () => {
    return (
        <BreakpointerProvider
            mode="development"
            classNames={{
                wrapper: ["bg-gray-300", "text-red-800", "p-4", "rounded-lg"],
                iconWrapper: ["content-start"],
                screen: ["font-bold", "text-lg", "text-blue-500"],
                currentWidth: ["text-sm", "text-gray-400"],
            }}
        >
            <App />
        </BreakpointerProvider>
    );
};

This configuration will style the BreakpointerIndicator according to the provided class names.