{"id":15784655,"url":"https://github.com/squirrel-forge/mediaquery-events","last_synced_at":"2026-05-07T14:40:34.564Z","repository":{"id":54913564,"uuid":"352996294","full_name":"squirrel-forge/mediaquery-events","owner":"squirrel-forge","description":"Use css media queries as javascript event names.","archived":false,"fork":false,"pushed_at":"2022-08-14T20:25:33.000Z","size":62,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-09T01:10:28.044Z","etag":null,"topics":["babel","es10","events","javascript","mediaqueries","webpack"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/squirrel-forge.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-30T12:39:52.000Z","updated_at":"2022-08-09T01:10:08.000Z","dependencies_parsed_at":"2022-08-14T06:30:41.713Z","dependency_job_id":null,"html_url":"https://github.com/squirrel-forge/mediaquery-events","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/squirrel-forge/mediaquery-events","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squirrel-forge%2Fmediaquery-events","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squirrel-forge%2Fmediaquery-events/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squirrel-forge%2Fmediaquery-events/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squirrel-forge%2Fmediaquery-events/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/squirrel-forge","download_url":"https://codeload.github.com/squirrel-forge/mediaquery-events/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squirrel-forge%2Fmediaquery-events/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264692295,"owners_count":23650459,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["babel","es10","events","javascript","mediaqueries","webpack"],"created_at":"2024-10-04T20:04:48.082Z","updated_at":"2025-10-29T05:05:18.603Z","avatar_url":"https://github.com/squirrel-forge.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @squirrel-forge/mediaquery-events\n**Use css media queries as javascript event names.**\nSimply don't worry about matching css media queries with custom javascript code, just bind a listener with the query as the event name and be done, the actual module, depending on how you use or implement it will be ~5kb in size.\n\n## Installation\n```\nnpm i @squirrel-forge/mediaquery-events\n```\n\n## Technical background and compatibility\nUnder the hood this uses **window.matchMedia**, **MediaQueryListEvent** and **CustomEvent**, it is, therefore only compatible with the more recent browsers, see details on [caniuse MediaQueryListEvent](https://caniuse.com/mdn-api_mediaquerylistevent_mediaquerylistevent) if the module would work for you.\n\nThere is a ponyFill available for browsers, for example: Safari \u003c 14, that do not allow *MediaQueryListEvent* objects to be constructed manually, but it must be included explicitly and is not included in the precompiled version.\n\nPolyfilling the missing parts is possible, please feel free to add a polyfill setup to make it compatible with older browsers such as IE11. The big desktop and mobile browsers such as Edge, Chrome, Opera, Firefox all support the required abilities of the api. There are currently no explicit plans to supply any complete polyfill for browsers that do not support all required features beyond the optional ponyFill for the *MediaQueryListEvent* constructor.\n\n---\n\n## Recommended usage:\n\n### Using es10 modules\nImport the required class and or ponyFill from the module, you have full control.\n```javascript\nimport { MediaQueryEvents, MediaQueryListEventPonyFill } from '@squirrel-forge/mediaquery-events';\n```\nCreate an instance with your preferred options.\n```javascript\nconst media = new MediaQueryEvents( {\n    \n    // Default target is the window object\n    //  target can be anything that provides the basic event methods:\n    //  addEventListener, removeEventListener, dispatchEvent\n    target : ( window | document | HTMLElement | Object ),\n    \n    // By default the ponyfill is null and not available\n    //  if set it will be used instead when the MediaQueryListEvent constructor cannot be called natively. \n    ponyfill : ( null | MediaQueryListEventPonyFill ),\n    \n    // By default debug is null\n    //  if set to console, it will supply error and event related information for debugging.\n    debug : ( null | console ),\n} );\n```\nNow you can start [binding events](#binding-and-using-media-query-events).\n\n---\n\n## Legacy usage:\n\n### Using the precompiled and minified webpack build\nImport or include a precompiled webpack version that attempts to bind to **window.media** and **window.mqe** as long as these are previously undefined.\n```javascript\nimport '@squirrel-forge/mediaquery-events/build/mediaquery-events.min.js';\n```\nOr:\n```html\n\u003cscript src=\".../@squirrel-forge/mediaquery-events/build/mediaquery-events.min.js\"\n```\nThe *media* binding can be overridden by setting your own names as following:\n```javascript\nwindow.mqe_OVERRIDE = [ 'reference' ];\n```\nThe *window.mqe* binding is always made unless defined and therefore blocked before loading the module.\nNow you can start [binding events](#binding-and-using-media-query-events).\n\n---\n\n## Binding and using media query events\n\n### for es10 and legacy\nDefine your event handlers.\n```javascript\n/**\n * Event handler \n * @private\n * @param {CustomEvent} event - Mediaquery custom event\n * @return {void}\n */\nconst _event_handler = ( event ) =\u003e {\n\n    // The event name the listener was bound to\n    //  if this is equal to event.detail.query this is not a global event\n    const listener = event.type;\n\n    // The media query string that is subject to this event\n    const query = event.detail.query;\n\n    // The query state\n    //  note this can be overridden when manually using MediaQueryEvents.dispatchEvent() to trigger a media query event\n    const matches = event.detail.event.matches;\n    \n    // Do something with this information\n    console.log( { listener, query, matches } );\n};\n```\nFor example, bind your handlers to queries that cover mobile, tablet and desktop:\n```javascript\nmedia.addEventListener( '(max-width: 767px)', _event_handler );\nmedia.addEventListener( '(min-width: 768px) and (max-width: 1024px)', _event_handler );\nmedia.addEventListener( '(min-width: 1025px)', _event_handler );\n```\nYou may also bind global events, these will fire for any query that was previously bound or required and changes it's state.\n```javascript\nmedia.addEventListener( 'media.on', _event_handler );\nmedia.addEventListener( 'media.off', _event_handler );\nmedia.addEventListener( 'media.change', _event_handler );\n```\n**Note**, that these only fire when at least one actual media query was bound or required.\n\nAll events can be bound to the given event target even before initializing the MediaQueryEvents Object:\n```javascript\nwindow.addEventListener( 'media.change', _event_handler );\nwindow.addEventListener( '(max-width: 375px)', _event_handler );\n```\nbut it is important to note that the events will only fire if the query is bound or required explicitly at some point:\n```javascript\nmedia.addEventListener( '(max-width: 375px)', _event_handler );\n\n// OR\n\nmedia.requireQueries( [ '(max-width: 375px)' ] );\n```\nIf you do not wish to bind the media queries directly and want to use the global events only,\nyou can initialize multiple required queries easily without binding any handlers.\n```javascript\n// Require an Array of queries\nmedia.requireQueries( [\n    '(max-width: 767px)',\n    '(min-width: 768px) and (max-width: 1024px)',\n    '(min-width: 1025px)',\n] );\n```\nUsing the *MediaQueryEvents.matches()* method returns the queries matching state.\nIt will create the given media query like the *requireQueries* method if it does not exist.\n```javascript\n// Check a queries state manually\nif ( media.matches( '(max-width: 767px)' ) ) {\n    // Do something\n}\n```\nCheck the example for working code [demo.js source file](example/src/demo.js).\n\n---\n\n## Class definitions\n\n### MediaQueryEvents\nMediaQueryEvents class - Supplies media query event functionality.\n\n#### Class overview\n```javascript\nclass MediaQueryEvents {\n    constructor( { target = window, ponyfill = null, debug = null } ) {}\n    target : window|document|HTMLElement|Object // Read only\n    debug : null|console // Settable Object\n    matches( query ) {} // Boolean|Null\n    requireQueries( queries ) {} // MediaQueryEvents\n    dispatchEvent( query, matches = null ) {} // MediaQueryEvents\n    addEventListener( query, callback, useCapture = false, dontFire = false ) {} // MediaQueryEvents\n    removeEventListener( query, callback, useCapture = false ) {} // MediaQueryEvents\n}\n```\nFor more details check the [MediaQueryEvents source file](src/MediaQueryEvents.js).\n\n#### Media query events\n - **{css media query}** - Fired whenever a query changes its state and matches.\n\n#### Global events\n - **media.on** - Fired once when a query goes active.\n - **media.off** - Fired once when a query goes inactive.\n - **media.change** - Fires in both cases described above.\n\n---\n\n### MediaQueryListEventPonyFill\nMediaQueryListEventPonyFill class - PonyFill class that provides a replacement object for when MediaQueryListEvent cannot be constructed.\n\n#### Class overview\n```javascript\nclass MediaQueryListEventPonyFill {\n    constructor( media, matches ) {}\n    media : string // read only\n    matches : boolean // ready only\n}\n```\nFor more details check the [MediaQueryListEventPonyFill source file](src/MediaQueryListEventPonyFill.js).\n\n---\n\n## Issues\nIf you encounter any issues, please report [here](https://github.com/squirrel-forge/mediaquery-event/issues).\n\n---\n\nCheck the sourcecode on [github](https://github.com/squirrel-forge/mediaquery-events) for detailed comments.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquirrel-forge%2Fmediaquery-events","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsquirrel-forge%2Fmediaquery-events","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquirrel-forge%2Fmediaquery-events/lists"}