CSS Element Queries

CSS Element Queries is a polyfill that adds support for element-based media queries to all browsers including IE7+. Unlike traditional media queries that depend on viewport size, this library enables CSS rules to respond to individual element dimensions, creating truly responsive components.

Package Information

• Package Name: css-element-queries
• Package Type: npm
• Language: JavaScript with TypeScript definitions
• Installation: npm install css-element-queries

Core Imports

const { ResizeSensor, ElementQueries } = require("css-element-queries");

For ES modules:

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

Basic Usage

Automatic CSS Element Queries (Recommended)

Include the scripts and element queries work automatically:

<script src="node_modules/css-element-queries/src/ResizeSensor.js"></script>
<script src="node_modules/css-element-queries/src/ElementQueries.js"></script>

Define CSS rules using attribute selectors:

.widget-name h2 {
    font-size: 12px;
}

.widget-name[min-width~="400px"] h2 {
    font-size: 18px;
}

.widget-name[min-width~="600px"] h2 {
    padding: 55px;
    text-align: center;
    font-size: 24px;
}

Manual Initialization

For module loaders, initialize manually:

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

// Attaches to DOMContentLoaded
ElementQueries.listen();

// OR manual initialization after DOM and CSS ready
ElementQueries.init();

Responsive Images

<div data-responsive-image>
    <img data-src="https://placehold.it/350x150"/>
    <img min-width="400" data-src="https://placehold.it/700x300"/>
    <img min-width="800" data-src="https://placehold.it/1400x600"/>
</div>

Architecture

CSS Element Queries consists of two main components:

• ResizeSensor: Core resize detection engine that efficiently monitors element dimension changes using event-based implementation
• ElementQueries: CSS parser and manager that discovers element query rules and attaches resize sensors to matching elements
• Event-based Implementation: No polling or intervals - uses requestAnimationFrame throttling for optimal performance
• Automatic Discovery: Automatically finds new DOM elements through MutationObserver

Capabilities

Element Resize Detection

Direct element resize detection for custom implementations and fine-grained control over resize handling.

class ResizeSensor {
  constructor(element: Element | Element[], callback: ResizeSensorCallback);
  detach(callback?: ResizeSensorCallback): void;
  reset(): void;
  static detach(element: Element | Element[], callback?: ResizeSensorCallback): void;
  static reset(element: Element | Element[]): void;
}

type ResizeSensorCallback = (size: { width: number; height: number }) => void;

Element Resize Detection

CSS Element Queries Management

Automatic CSS element query parsing and management for hands-off responsive behavior based on CSS rules.

class ElementQueries {
  static listen(): void;
  static init(): void;
  static update(): void;
  static detach(element: Element): void;
  static findElementQueriesElements(container: Element): void;
}

CSS Element Queries Management

Responsive Images

Built-in responsive image functionality that automatically switches image sources based on container dimensions, providing optimal images without layout shifts.

<div data-responsive-image>
    <img data-src="small.jpg"/>
    <img min-width="400" data-src="medium.jpg"/>
    <img min-width="800" data-src="large.jpg"/>
</div>

Responsive Images

CSS Syntax

Element queries use standard CSS attribute selectors with these supported attributes:

• min-width - Minimum width queries
• min-height - Minimum height queries
• max-width - Maximum width queries
• max-height - Maximum height queries

Always use the ~= attribute selector:

.element[min-width~="400px"] { /* styles */ }
.element[max-height~="600px"] { /* styles */ }