CSS Element Queries Management

The ElementQueries class automatically parses CSS stylesheets for element query rules and attaches ResizeSensor instances to matching elements. This provides hands-off responsive behavior where CSS rules are applied based on individual element dimensions.

Capabilities

Listen

Attaches to DOMContentLoaded event and automatically initializes element queries when the DOM is ready.

/**
 * Attaches to DOMContentLoaded event for automatic initialization
 */
static listen(): void;

Usage Examples:

import { ElementQueries } from "css-element-queries";

// Automatic initialization on DOM ready
ElementQueries.listen();

Init

Parses all available CSS and attaches ResizeSensor to those elements which have element query rules. Make sure this is called after the 'load' event, because CSS files are not ready when domReady is fired.

/**
 * Parses CSS and attaches resize sensors to elements with query rules
 */
static init(): void;

Usage Examples:

// Manual initialization after DOM and CSS are ready
window.addEventListener('load', function() {
    ElementQueries.init();
});

// Or call directly if CSS is already loaded
ElementQueries.init();

Update

Re-evaluates all elements with element query rules and updates their query attributes based on current dimensions. This is automatically called by init() but can be useful after dynamic content changes.

/**
 * Updates element queries by re-evaluating all elements
 */
static update(): void;

Usage Examples:

// Force update after programmatic layout changes
document.getElementById('container').style.width = '800px';
ElementQueries.update();

// Update after adding new CSS rules dynamically
const style = document.createElement('style');
style.textContent = '.widget[min-width~="500px"] { color: blue; }';
document.head.appendChild(style);
ElementQueries.update();

Detach

Removes element query functionality from a specific element, detaching its resize sensor and cleaning up query attributes.

/**
 * Detaches element queries from specified element
 * @param element - Element to remove queries from
 */
static detach(element: Element): void;

Usage Examples:

// Remove element queries from specific element
const element = document.getElementById('responsive-widget');
ElementQueries.detach(element);

Find Element Queries Elements

Searches for elements with element query rules within a container and processes them.

/**
 * Searches for elements with element query rules within a container
 * @param container - Container element to search within
 */
static findElementQueriesElements(container: Element): void;

Usage Examples:

// Process new elements added to specific container
const newContainer = document.getElementById('dynamic-content');
ElementQueries.findElementQueriesElements(newContainer);

CSS Element Query Syntax

Element queries use CSS attribute selectors to define responsive rules based on element dimensions.

Supported Query Attributes

• min-width - Element must be at least this wide
• min-height - Element must be at least this tall
• max-width - Element must be no wider than this
• max-height - Element must be no taller than this

CSS Syntax

Always use the ~= attribute selector since multiple query values may be applied:

/* Basic element queries */
.widget[min-width~="400px"] {
    font-size: 18px;
}

.widget[min-height~="300px"] {
    padding: 20px;
}

/* Multiple queries */
.widget[min-width~="400px"][min-height~="300px"] {
    background: lightblue;
}

/* Complex selectors */
.widget[min-width~="600px"] .header {
    font-size: 24px;
    text-align: center;
}

Generated Attributes

The polyfill adds attributes to elements based on their current dimensions:

<!-- Before -->
<div class="widget">Content</div>

<!-- After (when element is 450px wide and 200px tall) -->
<div class="widget" min-width="400px" max-width="600px">Content</div>

Usage Patterns

Automatic Usage (Recommended)

Include both scripts and element queries work automatically:

<script src="src/ResizeSensor.js"></script>
<script src="src/ElementQueries.js"></script>

The ElementQueries script automatically calls listen() when included globally.

Module Loader Usage

For webpack, rollup, or other module bundlers:

import { ElementQueries } from "css-element-queries";

// Option 1: Automatic initialization
ElementQueries.listen();

// Option 2: Manual control
window.addEventListener('load', () => {
    ElementQueries.init();
});

Dynamic Content

For dynamically added content:

// After adding new elements to the DOM
const container = document.getElementById('dynamic-container');
container.innerHTML = '<div class="widget">New content</div>';

// Process new elements
ElementQueries.findElementQueriesElements(container);

Performance Characteristics

• CSS Parsing: Scans all stylesheets once during initialization
• Selective Monitoring: Only adds ResizeSensor to elements with query rules
• Automatic Discovery: Uses MutationObserver to find new elements
• Throttled Updates: Resize callbacks are throttled via requestAnimationFrame

Browser Compatibility

• IE7+ (with limitations on some CSS features)
• All modern browsers
• Works with dynamically loaded CSS
• Compatible with CSS3 transitions and animations

Limitations

• Does not work on img and other elements that can't contain child elements (wrap with a div)
• Adds hidden child elements and forces position: relative or absolute
• Local stylesheets using file:// protocol are not supported
• CSS animations on query elements should include element-queries animation name