or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdregistration.md
tile.json

registration.mddocs/

Query Registration and Management

Core functionality for registering and managing media query handlers with various handler formats and lifecycle management.

Capabilities

Register Query Handler

Registers handlers for a given media query with support for multiple handler formats.

/**
 * Registers handlers for a given media query
 * @param {string} query - CSS media query string (e.g., "screen and (max-width: 768px)")
 * @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);

Handler Formats:

  1. Function Handler: Simple function called when query matches (automatically normalized to {match: function})
  2. Object Handler: Object with lifecycle callbacks (match, unmatch, setup, destroy)
  3. Array of Handlers: Multiple handlers for the same query (functions are normalized, objects used as-is)

Handler Normalization:

enquire.js automatically normalizes different handler formats:

  • Functions become {match: functionReference}
  • Objects are used directly
  • Arrays are processed with each element normalized individually

Usage Examples:

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

// Function handler - called when query matches
enquire.register("screen and (max-width: 768px)", function() {
    console.log('Mobile view active');
});

// Object handler with lifecycle callbacks
enquire.register("screen and (min-width: 769px)", {
    match: function() {
        // Called when query starts matching
        document.body.classList.add('desktop-view');
    },
    unmatch: function() {
        // Called when query stops matching
        document.body.classList.remove('desktop-view');
    },
    setup: function() {
        // Called once on registration
        console.log('Desktop handler initialized');
    },
    destroy: function() {
        // Called when handler is destroyed
        console.log('Desktop handler destroyed');
    },
    deferSetup: false  // Run setup immediately (default)
});

// Array of handlers
enquire.register("screen and (max-width: 480px)", [
    {
        match: function() { console.log('Handler 1: mobile'); }
    },
    function() { console.log('Handler 2: mobile'); }
]);

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

Unregister Query Handler

Removes media query handlers and cleans up resources.

/**
 * Unregisters query handlers - removes all handlers if no specific handler provided
 * @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);

Behavior:

  • Without handler parameter: Removes all handlers for the query and deletes the query entirely
  • With handler parameter: Removes only the specific handler, keeps other handlers for the same query
  • Handler matching: Uses reference equality for objects, or matches the match function for function handlers
  • Cleanup: Calls destroy() method on removed handlers, or unmatch() if destroy() is not available

Usage Examples:

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

// Remove all handlers for a query
enquire.unregister("screen and (max-width: 768px)");

// Remove specific handler
const myHandler = function() { console.log('mobile'); };
enquire.register("screen and (max-width: 768px)", myHandler);
enquire.unregister("screen and (max-width: 768px)", myHandler);

// Remove specific object handler
const myObjectHandler = {
    match: function() { console.log('matched'); }
};
enquire.register("screen and (max-width: 768px)", myObjectHandler);
enquire.unregister("screen and (max-width: 768px)", myObjectHandler);

Handler Object Properties

/**
 * Handler object interface with optional lifecycle callbacks
 */
interface Handler {
    /** 
     * Callback fired when media query transitions from unmatched to matched state
     * @function
     */
    match?: function();
    
    /** 
     * Callback fired when media query transitions from matched to unmatched state
     * Also may be called when handler is unregistered (if destroy is not available)
     * @function
     */
    unmatch?: function();
    
    /** 
     * One-time callback triggered immediately upon registration of the handler
     * If deferSetup is true, deferred until first match
     * @function
     */
    setup?: function();
    
    /** 
     * Callback triggered when handler is unregistered for cleanup
     * If not provided, unmatch callback is used instead
     * @function
     */
    destroy?: function();
    
    /** 
     * Whether to defer execution of setup function until first match
     * @type {boolean}
     * @default false
     */
    deferSetup?: boolean;
}

Legacy Browser Support

/**
 * Support for legacy browsers that don't properly support media queries
 * @param {boolean} shouldDegrade - Whether this query should always run on incapable browsers
 */
enquire.register(query, handler, shouldDegrade);

Browser Capability Detection:

enquire.js automatically detects browser capability by testing window.matchMedia('only all').matches. When shouldDegrade is true and the browser is detected as incapable, queries will always run regardless of the actual media query conditions.

Usage Examples:

// Always run mobile handlers on legacy browsers
enquire.register(
    "screen and (max-width: 768px)", 
    mobileHandler, 
    true  // shouldDegrade - runs on incapable browsers
);

// Standard behavior - only runs when query matches
enquire.register(
    "screen and (max-width: 768px)", 
    mobileHandler, 
    false  // default - respects media query conditions
);

Method Chaining

All registration methods return the enquire instance for chaining:

enquire
    .register("screen and (max-width: 480px)", phoneHandler)
    .register("screen and (min-width: 481px) and (max-width: 768px)", tabletHandler)  
    .register("screen and (min-width: 769px)", desktopHandler)
    .unregister("screen and (max-width: 480px)")  // Remove phone handler
    .register("screen and (max-width: 600px)", newMobileHandler);