{"id":17651363,"url":"https://github.com/nash403/fine-mq","last_synced_at":"2025-08-22T09:33:19.465Z","repository":{"id":38375557,"uuid":"140600156","full_name":"nash403/fine-mq","owner":"nash403","description":"A fine API to manage media queries in JS with ease. It has first-class integration with VueJS.","archived":false,"fork":false,"pushed_at":"2023-01-07T22:33:19.000Z","size":2702,"stargazers_count":22,"open_issues_count":17,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-14T13:43:53.624Z","etag":null,"topics":["matchmedia","media-queries","media-query","mobile","mobile-first","mq","nuxt","nuxt-mq","responsive","rwd","vue-plugin"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/nash403.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-07-11T16:12:51.000Z","updated_at":"2023-05-03T09:08:41.000Z","dependencies_parsed_at":"2023-02-08T03:01:16.281Z","dependency_job_id":null,"html_url":"https://github.com/nash403/fine-mq","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nash403%2Ffine-mq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nash403%2Ffine-mq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nash403%2Ffine-mq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nash403%2Ffine-mq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nash403","download_url":"https://codeload.github.com/nash403/fine-mq/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251714932,"owners_count":21631806,"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":["matchmedia","media-queries","media-query","mobile","mobile-first","mq","nuxt","nuxt-mq","responsive","rwd","vue-plugin"],"created_at":"2024-10-23T11:41:57.536Z","updated_at":"2025-04-30T13:51:20.535Z","avatar_url":"https://github.com/nash403.png","language":"TypeScript","funding_links":[],"categories":["UI实用程序","Components \u0026 Libraries","UI Utilities","UI Utilities [🔝](#readme)"],"sub_categories":["响应式设计","UI Utilities","Responsive Design"],"readme":"# fine-mq\n\n\u003e A fine API to use media queries in JS with ease and with first-class integration with Vue.js/Nuxt.js.\n\nRead the doc [here](https://nash403.github.io/fine-mq/).\n\n```sh\n# Install using NPM or Yarn:\nnpm i --save fine-mq\n# or\nyarn add fine-mq\n```\n\n## Usage\n\n### In JS\n\n```js\nimport { createFineMediaQueries }  from 'fine-mq'\n\nconst mq = createFineMediaQueries({\n  // Fine Mq supports modifiers for sizes shortcuts  (see below for examples)\n  sm: 680, // \u003c=\u003e [0, 680]\n  md: [681, 1024],\n  lg: [1025], // \u003c=\u003e [1025, Infinity]\n  landscape: '(orientation: landscape)',\n  custom1: 'only screen and (max-width: 480px)',\n  custom2: 'only screen and (min-width: 480px) and (max-width: 720px)',\n  an_alias_object: {\n    screen: true,\n    minWidth: '23em',\n    maxWidth: '768px'\n  }\n})\n\n// =\u003e This example will register the following aliases:\n// {\n//   sm: '(max-width: 680px)',\n//   'sm+': '(min-width: 681px)',\n//   md: '(min-width: 681px) and (max-width: 1024px)',\n//   'md+': '(min-width: 1025px)',\n//   'md!': '(min-width: 681px)',\n//   lg: '(min-width: 1025px)',\n//   landscape: '(orientation: landscape)',\n//   an_alias_name: 'screen and (min-width: 380px) and (max-width: 768px)'\n// }\n\n// !: means «current and above»\n// +: means «above»\n\nconst defaultColor = '#FFF'\n\nconst changeColor = color =\u003e ({ matches, mediaQuery, alias }) =\u003e {\n  document.body.style.backgroundColor = matches ? color : defaultColor\n}\n\nmq.on('small', changeColor('blue'))\nmq.on('medium', changeColor('green'))\nmq.on({\n  screen: true,\n  maxWidth: '1200px'\n}, changeColor('cyan'))\nmq.on('only screen and (min-width: 720px)', changeColor('red'))\nmq.off('only screen and (min-width: 720px)')\n```\n\n_**NOTE 1:**_ Absurd modifiers will not be created for  (ex: when the lower bound is _0_, there is no need for the «!» modifier, or if the upper bound is _Infinity_, there is no need for both «!» and «+» modifiers).\n\n_**NOTE 2:**_ If you specify the unit for your size (`px`, `em`, `rem`), the `+ 1` operation will not be performed for modifiers.\n\nSee [FineMq](#finemq-api) for details about the API.\n\n### As a Vue plugin\n\n```js\nimport { FineMqPlugin } from 'fine-mq'\n\n\n// Define your aliases as plugin options (defaults to `{ sm: 680, md: [681, 1024], lg: [1025] }` for Vue.js only, not the JS API)\nVue.use(FineMqPlugin, {\n  aliases: {\n    sm: 680, // \u003c=\u003e [0, 680], can also be a size in px, em or rem\n    md: [681, 1024],\n    lg: [1025], // \u003c=\u003e [1025, Infinity]\n    landscape: '(orientation: landscape)',\n    an_alias_name: {\n      screen: true,\n      minWidth: '23em',\n      maxWidth: '768px'\n    }\n  }\n  // Define the default values for your matching aliases for SSR\n  defaultMatchedMediaQueries: {\n    sm: false,\n    md: false,\n    lg: true,\n  }\n})\n\n// Three reactive properties will then be available on Vue instances:\n// - `$mq` is an object that contains the matching state for each alias in the form { [alias]: true/false }.\n// - `$lastActiveAlias` will contain the last alias that was matched and triggered by the listener.\n// - `$fineMq` is a FineMq instance for advanced usages.\n```\n\n### With Nuxt.js\n\n```js\n// In your nuxt.config.js\nexport default {\n  // ...\n  \n  // Build Configuration (https://go.nuxtjs.dev/config-build)\n  build: {\n    transpile: ['fine-mq'],\n  },\n  \n  modules: ['fine-mq/nuxt'],\n\n  // Pass options here\n  fineMq: {\n    defaultMatchingAliases: {\n      md: true,\n    },\n    aliases: {\n      sm: 640,\n      md: [641, 768],\n      lg: [769, 1024],\n      xl: [1025, 1280],\n      '2xl': [1281],\n    },\n  },\n\n  // ...\n}\n```\n\n## FineMq API\n\n### const mq = createFineMediaQueries(aliases, defaultMatchedMediaQueries)\n\nInitialize helpers for your media query aliases. Other aliases can be registered afterwards.\n\n`defaultMatchedMediaQueries` is for universal apps that need default values on SSR.\n\n### mq.addAlias(alias[, query]) / mq.removeAlias(alias)\n\nRegister an `alias` for a `query`, or register multiple aliases at once by passing an object.\n\n```js\nmq.addAlias('small', '(max-width: 100px)')\nmq.addAlias({\n  small: '(max-width: 100px)',\n  medium: {\n    screen: true,\n    maxWidth: 200\n  },\n})\n```\n\nThen you can unregister previously registered aliases with `mq.removeAlias(alias)`.\n\n### mq.on(query, callback)\n\nRegister a `callback` which will be executed everytime the match state (true/false) for a query or alias changes.\n\n```js\n// `alias` is the given alias, mediaQuery is the actual media query matched and `matches` is a boolean indicating the match state.\nmq.on('(max-width: 400px)', ({ matches, alias, mediaQuery }) =\u003e {})\nconst unregister = mq.on('smartphones', ({ matches, alias, mediaQuery }) =\u003e {}, {})\n\nunregister() // this removes the handler you just added.\n```\n\n### mq.off(query, callback)\n\nRemove all handlers for all media queries:\n\n```js\nmq.off()\n```\n\nRemove all handlers for a media query or alias:\n\n```js\nmq.off('(max-width: 400px)')\nmq.off('small')\n```\n\nRemove a specific handler for a query or alias:\n\n```js\nmq.off('(max-width: 400px)', myHandler)\nmq.off('small', myHandler)\n```\n\n## Browser Support\n\nThis library relies on matchMedia API to detect screensize change. You can use a polyfill if you need this package to work for older browsers. Check this out:\nPaul Irish: [matchMedia polyfill](https://github.com/paulirish/matchMedia.js)\n\n## Credits\n\nThis package is highly inspired by the work made on other packages (links below), I just shamelessly copied their work and combined them !\n\n- [media-query-facade](https://github.com/tanem/media-query-facade) by @tanem\n- [vue-mq](https://github.com/AlexandreBonaventure/vue-mq/) by @AlexandreBonaventure\n- [json2mq](https://github.com/akiran/json2mq) by @akiran\n\n## Contributing\n\nPlease [open an issue](https://github.com/nash403/fine-mq/issues/new) for support. Thanks in advance for any kind of contribution !\n\n1. Fork it!\n2. Create your feature branch: git checkout -b my-new-feature\n3. Commit your changes: git commit -am 'Add some feature'\n4. Push to the branch: git push origin my-new-feature\n5. Submit a pull request :D\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnash403%2Ffine-mq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnash403%2Ffine-mq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnash403%2Ffine-mq/lists"}