tessl/npm-respond-js

Fast and lightweight polyfill for min/max-width CSS3 Media Queries for IE 6-8 and more

—

Pending

Overview

Eval results

Files

matchMedia Polyfill

Name: tessl/npm-respond-js
Author: tessl

The matchMedia polyfill provides window.matchMedia functionality for browsers that don't support it natively. This enables testing CSS media queries programmatically in JavaScript, essential for responsive JavaScript behavior.

Capabilities

window.matchMedia Function

Creates MediaQueryList objects for testing media queries in JavaScript.

/**
 * Test a CSS media query in JavaScript
 * Creates a temporary DOM element to test if the media query matches
 * @param query - CSS media query string to test
 * @returns MediaQueryList object with match result and query string
 */
declare function matchMedia(query: string): MediaQueryList;

interface MediaQueryList {
  /** Whether the media query currently matches the viewport */
  matches: boolean;
  /** The original media query string that was tested */
  media: string;
}

Usage Examples:

// Test viewport width
var mql = matchMedia('(min-width: 768px)');
if (mql.matches) {
  console.log('Viewport is at least 768px wide');
} else {
  console.log('Viewport is less than 768px wide');
}

// Test different media types
var printQuery = matchMedia('print');
if (printQuery.matches) {
  console.log('Print styles are active');
}

// Test complex queries
var complexQuery = matchMedia('screen and (min-width: 480px) and (max-width: 1024px)');
if (complexQuery.matches) {
  console.log('Medium-sized screen detected');
}

MediaQueryList Interface

Result object returned by matchMedia calls.

interface MediaQueryList {
  /** 
   * Boolean indicating whether the media query matches current conditions
   * Updated each time matchMedia is called with the same query
   */
  matches: boolean;
  
  /** 
   * The original media query string passed to matchMedia
   * Preserved exactly as provided
   */
  media: string;
}

Implementation Details

Testing Mechanism

The polyfill works by creating a temporary DOM structure to test media queries:

Temporary Elements: Creates a hidden div and style element
CSS Injection: Injects a test CSS rule with the media query
Dimension Check: Measures the test element to determine if the query matches
Cleanup: Removes temporary elements after testing

Browser Compatibility

IE 9+: Native matchMedia support (polyfill not used)
IE 6-8: Polyfill provides full functionality
Modern Browsers: Native implementation used when available
Early Exit: Polyfill detects native support and defers to it

Test CSS Pattern

/* Example of injected test CSS */
@media (min-width: 768px) { 
  #mq-test-1 { width: 42px; } 
}

The polyfill checks if the test element (#mq-test-1) has a width of 42px to determine if the media query matches.

Supported Query Types

The matchMedia polyfill supports the same media query features as the main respond.js library:

Width queries: min-width, max-width
Media types: screen, print, all, etc.
Units: px, em
Complex queries: Multiple conditions with 'and'

Query Parsing Examples

// Simple width queries
matchMedia('(min-width: 600px)').matches;
matchMedia('(max-width: 1200px)').matches;

// Media type queries
matchMedia('screen').matches;
matchMedia('print').matches;

// Complex combined queries
matchMedia('screen and (min-width: 768px)').matches;
matchMedia('screen and (min-width: 480px) and (max-width: 1024px)').matches;

// Em-based queries
matchMedia('(min-width: 30em)').matches;
matchMedia('(max-width: 60em)').matches;

Integration with Respond.js

Bundled Versions

The matchMedia polyfill is included in certain respond.js distributions:

respond.src.js: Includes matchMedia polyfill + core respond.js
respond.matchmedia.addListener.src.js: Includes matchMedia + addListener + core

Standalone Usage

The matchMedia polyfill can be used independently of respond.js for projects that only need programmatic media query testing without CSS polyfill functionality.

<!-- Standalone matchMedia polyfill -->
<script src="matchmedia.polyfill.js"></script>

<script>
// Now available in all browsers
if (matchMedia('(min-width: 768px)').matches) {
  // JavaScript for larger screens
}
</script>

Conditional Loading

// Check if matchMedia is already available
if (!window.matchMedia) {
  // Load polyfill only if needed
  var script = document.createElement('script');
  script.src = 'matchmedia.polyfill.js';
  document.head.appendChild(script);
}

Performance Considerations

Caching

The polyfill creates fresh DOM elements for each test, so frequent matchMedia calls with the same query should store the result:

// Inefficient - creates new test elements each time
function checkViewport() {
  return matchMedia('(min-width: 768px)').matches;
}

// Better - cache the MediaQueryList object
var desktopQuery = matchMedia('(min-width: 768px)');
function checkViewport() {
  return desktopQuery.matches;
}

Timing

The polyfill involves DOM manipulation, so it's best called:

During initialization
In response to resize events (with throttling)
Before layout-dependent operations

// Good usage pattern
var queries = {
  mobile: matchMedia('(max-width: 767px)'),
  tablet: matchMedia('(min-width: 768px) and (max-width: 1023px)'),
  desktop: matchMedia('(min-width: 1024px)')
};

function handleResize() {
  if (queries.mobile.matches) {
    // Mobile layout
  } else if (queries.tablet.matches) {
    // Tablet layout  
  } else if (queries.desktop.matches) {
    // Desktop layout
  }
}

Install with Tessl CLI