React Media Queries

A lightweight, performant React hooks library for responsive design and media query management. Built with TypeScript and optimized for modern React applications, including SSR support.

Table of Contents

• Features
• Installation
• Demo
• Usage
• API Reference
• SSR Support
• License
• Contributing
• Contributors

Features

• 🚀 Performant: Uses useSyncExternalStore for optimal performance and React 18+ compatibility
• 🔄 SSR Compatible: Handles server-side rendering gracefully
• 🎯 TypeScript: Full TypeScript support with type definitions
• 🪝 Hooks-Based: Modern React hooks API
• ⚡ Efficient: Shared stores prevent duplicate media query listeners

Installation

npm install @alejandrorm-dev/react-media-queries

Demo

https://github.com/user-attachments/assets/dd7719a8-a3bd-4da5-93c2-126bdfc8ceb7

Usage

import { useMediaQuery } from "@alejandrorm-dev/react-media-queries";

function ResponsiveComponent() {
	const isLargeScreen = useMediaQuery("(min-width: 1200px)");

	return (
		<div>{isLargeScreen ? "Large screen layout" : "Small screen layout"}</div>
	);
}

API Reference

useMediaQuery(query: string): boolean

Evaluates a single CSS media query and returns its current match state.

Parameters:

• query (string): The CSS media query string to evaluate (e.g., "(min-width: 768px)")

Returns: boolean - true if the media query matches, false otherwise. Returns false during SSR.

Example:

const isTablet = useMediaQuery("(min-width: 768px) and (max-width: 1024px)");

SSR Support

The hook is designed to work seamlessly in server-side rendering environments. During SSR, useMediaQuery returns false. On the client, the value updates to reflect the actual media query state.

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!