Alpine.js Breakpoint Directive

A lightweight Alpine.js plugin that exposes CSS-like breakpoints directly to your Alpine components using a simple directive. It allows you to reactively track whether the viewport width matches a given breakpoint.

This plugin is framework-agnostic but pairs especially well with Tailwind-style breakpoint definitions.

Features

• 📐 Reactive viewport breakpoint detection
• ⚡ Minimal and lightweight
• 🧩 Simple Alpine directive API
• 🪄 Works with any breakpoint configuration (px, rem, em, etc.)
• 🧼 Automatic cleanup on component removal

Installation

npm install alpinejs-breakpoint

or

yarn add alpinejs-breakpoint

Usage

1. Register the plugin

Import the plugin and register it with Alpine, passing your breakpoint configuration.

import Alpine from 'alpinejs';
import breakpoint from 'alpinejs-breakpoint';

Alpine.plugin(
    breakpoint({
        sm: '31.25rem',
        md: '43.75rem',
        lg: '62.5rem',
        xl: '87.5rem',
    })
);

Alpine.start();

💡 The values can be any valid CSS width units (px, rem, em, etc.).

2. Use the x-breakpoint directive

The directive syntax is:

x-breakpoint:<name>="<expression>"

• <name> — the breakpoint key from your configuration
• <expression> — an Alpine expression (usually a variable) that will be set to true or false

Example

<div
    x-data="{
        isSmall: false,
        isMedium: false,
        isLarge: false,
        isExtraLarge: false,
    }"
    x-breakpoint:sm="isSmall"
    x-breakpoint:md="isMedium"
    x-breakpoint:lg="isLarge"
    x-breakpoint:xl="isExtraLarge"
>
    <p><code>isSmall: <span x-text="isSmall"></span></code></p>
    <p><code>isMedium: <span x-text="isMedium"></span></code></p>
    <p><code>isLarge: <span x-text="isLarge"></span></code></p>
    <p><code>isExtraLarge: <span x-text="isExtraLarge"></span></code></p>
</div>

Each variable automatically updates when the viewport crosses its breakpoint threshold.

How It Works

• Internally uses window.matchMedia() with modern range syntax:

(width >= breakpoint)

• Evaluates immediately on initialization
• Listens to resize events
• Updates values with a small debounce (150ms)
• Automatically removes event listeners when the element is destroyed

Notes

• If a breakpoint name is not found in the configuration, the directive does nothing.
• This plugin only checks minimum width (>=), similar to Tailwind's breakpoint behavior.
• Designed for client-side usage only.