or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdregistration.md
tile.json

tessl/npm-enquire-js

Awesome Media Queries in JavaScript

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/enquire.js@2.1.x

To install, run

npx @tessl/cli install tessl/npm-enquire-js@2.1.0

index.mddocs/

enquire.js

enquire.js is a lightweight, pure JavaScript library with no dependencies for programmatically responding to CSS media queries. It provides a simple API centered around the register() method that allows developers to define handlers for CSS media query states, supporting match/unmatch callbacks, setup/destroy lifecycle methods, and deferred setup options.

Package Information

  • Package Name: enquire.js
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install enquire.js

Core Imports

// CommonJS (primary)
const enquire = require('enquire.js');

// ES Module (if supported by bundler)
import enquire from 'enquire.js';

// Browser global (from CDN)
// enquire is available as a global variable

Basic Usage

const enquire = require('enquire.js');

// Register a handler for a media query
enquire.register("screen and (max-width: 1000px)", {
    match: function() {
        // Triggered when media query matches
        console.log('Mobile view activated');
    },
    unmatch: function() {
        // Triggered when media query no longer matches  
        console.log('Desktop view activated');
    },
    setup: function() {
        // One-time setup when handler is registered
        console.log('Handler initialized');
    }
});

// Simple function handler
enquire.register("screen and (min-width: 1200px)", function() {
    console.log('Large screen detected');
});

Architecture

enquire.js is built around several key components:

  • MediaQueryDispatch: Main API class that manages query registration and browser compatibility
  • MediaQuery: Represents individual media queries and manages their state
  • QueryHandler: Wraps handler objects and manages their lifecycle
  • Browser Integration: Uses native window.matchMedia API with graceful fallbacks

The library uses a singleton pattern where the main export is a pre-instantiated MediaQueryDispatch object.

Capabilities

Query Registration

Primary API for registering media query handlers with various handler formats and lifecycle callbacks.

/**
 * Registers handlers for a given media query
 * @param {string} query - CSS media query string
 * @param {object|function|array} handler - Handler object, function, or array of handlers
 * @param {boolean} [shouldDegrade=false] - Whether query should always run on incapable browsers
 * @returns {object} enquire instance for method chaining
 */
enquire.register(query, handler, shouldDegrade);

Method Chaining: All registration methods return the enquire instance, allowing for fluent method chaining:

enquire
  .register("screen and (max-width: 768px)", mobileHandler)
  .register("screen and (min-width: 769px)", desktopHandler)
  .unregister("screen and (max-width: 480px)");

Query Registration

Query Unregistration

API for removing media query handlers and cleaning up resources.

/**
 * Unregisters query handlers
 * @param {string} query - CSS media query string to target
 * @param {object|function} [handler] - Specific handler to remove (optional)
 * @returns {object} enquire instance for method chaining
 */
enquire.unregister(query, handler);

Query Unregistration

Types

/**
 * Handler object interface
 */
interface Handler {
  /** Callback fired when query transitions from unmatched to matched */
  match?: function();
  /** Callback fired when query transitions from matched to unmatched */
  unmatch?: function(); 
  /** One-time callback triggered on registration or first match */
  setup?: function();
  /** Callback for cleanup when handler is unregistered */
  destroy?: function();
  /** Whether to defer setup until first match (default: false) */
  deferSetup?: boolean;
}

Error Handling

  • No matchMedia Support: Throws Error 'matchMedia not present, legacy browsers require a polyfill' if window.matchMedia is not available
  • Browser Capability Detection: Automatically detects browser capability using window.matchMedia('only all').matches
  • Invalid Handlers: Gracefully handles missing optional handler callbacks (match, unmatch, setup, destroy)
  • Query Registration: Normalizes function handlers to object format automatically
  • Cleanup: Automatic cleanup when queries are unregistered or destroyed, including event listener removal