Alpine.js Responsive Plugin

Supercharge your Alpine.js apps with responsive superpowers! 🚀

A lightweight Alpine.js plugin that simplifies managing responsive behaviors and conditional attributes. This plugin provides utilities to manage media query states and apply conditional attributes or values based on screen size.

🌟 Features

• 📱 Media Query State Management: Instantly know if your user is on mobile or desktop.
• ✨ Magic Helpers: Use media and getMobileValue to make your components smarter.
• 🎨 Custom Directive: Dynamically add or remove attributes with x-mobileattributes.

🛠️ Installation

Getting started with Responsive is a breeze! With just a few lines of code, you'll unlock the power of responsive design in your Alpine.js projects.

Via NPM

1. Install the plugin with npm:

npm install @cesarfernandoig/alpine-responsive-plugin

2. Import and initialize the plugin in your project:

import Alpine from 'alpinejs';
import responsive from '@cesarfernandoig/alpine-responsive-plugin';

Alpine.plugin(responsive);
Alpine.start();

Via CDN

If you prefer using a CDN, simply include the following script tag in your HTML file, make sure to include it BEFORE Alpine's core JS file:

<!-- Alpine Plugins -->
<script defer src="https://cdn.jsdelivr.net/npm/@cesarfernandoig/[email protected]/dist/responsive.min.js"></script>

<!-- Alpine Core -->
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/cdn.min.js"></script>

🎮 Usage

Now that the plugin is set up, let’s explore the magic! You can use the features provided by Responsive to make your site smarter and more responsive.

🪄 Magic: $media

The media magic helper gives you access to isMobile and isDesktop properties. You can use these properties anywhere in your Alpine.js components to apply logic based on screen size.

Example:

<div x-data>
  <span x-text="$media.isMobile ? '📱 On Mobile!' : '🖥️ On Desktop!'"></span>
</div>

• $media.isMobile is true if the screen width is less than 768px.
• $media.isDesktop is true if the screen width is 768px or greater.

🪄 Magic: $getMobileValue

The $getMobileValue magic helper is your go-to for conditional values. It’s like having a chameleon that adapts to the device type! 🦎

Example:

<div x-data>
  <span x-text="$getMobileValue('This is for mobile 🐳', 'This is for desktop 🦖')"></span>
</div>

• If the device is mobile, it returns 'This is for mobile 🐳'.
• If the device is desktop, it returns 'This is for desktop 🦖'.

🖌️ Directive: x-mobileattributes

Want to conditionally add/remove attributes based on screen size? Look no further than the x-mobileattributes directive! You can pass in a set of attributes and their values for mobile and desktop resolutions, and Responsive will handle the rest.

Example:

<button
	type="button"
	x-mobileattributes="{
        title: ['Snake', 'Turtle'],
        'x-text': ['`🐍`', '`🐢`'],
        class: 'snake-class'
    }"
	>
</button>

• Mobile: Sets the title to "Snake", x-text to "🐍", and applies the snake-class.
• Desktop: Sets the title to "Turtle", x-text to "🐢", and removes the class attribute (since it doesn't have a desktop value — similar to writing class: ['snake-class', null]).

💡 Pro Tip:

By combining Responsive with Alpine’s built-in directives like x-show, x-if, or x-transition, you can create rich and highly dynamic UI elements tailored for different screen sizes.

🧑‍💻 API Reference

🪄 Magics

• $media: Returns a reactive object with isMobile and isDesktop properties.

$media.isMobile; // true if mobile
$media.isDesktop; // true if desktop

• $getMobileValue(mobileValue, desktopValue): Returns mobileValue if the device is mobile, otherwise returns desktopValue.

getMobileValue('📱 Mobile', '🖥️ Desktop'); // '📱 Mobile' or '🖥️ Desktop'

🖌️ Directives

• x-mobileattributes: Applies or removes attributes conditionally.

<div x-mobileattributes="{ 'attribute': [mobileValue, desktopValue] }"></div>

🤝 Contributing

We 💖 contributions! If you have an idea, found a bug, or just want to improve the plugin, feel free to jump in!

1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Submit a pull request.

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.

🙏 Acknowledgments

A huge shoutout to Alpine.js for making JavaScript fun and simple!

🚀 Ready to Go Responsive?

With this plugin, handling responsiveness in your Alpine.js apps has never been easier. Install it today and start building smarter, more dynamic interfaces! 🎉