{"id":15103469,"url":"https://github.com/contentco/angular-match-media","last_synced_at":"2025-09-27T01:30:56.781Z","repository":{"id":57195244,"uuid":"204653134","full_name":"contentco/angular-match-media","owner":"contentco","description":"Angular module to use Bootstrap3 media queries in your angular controllers.","archived":false,"fork":true,"pushed_at":"2019-08-28T05:52:20.000Z","size":51,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-12-17T08:42:15.469Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://jack.ofspades.com/angular-matchmedia-module/","language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"jacopotarantino/angular-match-media","license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/contentco.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-08-27T08:10:18.000Z","updated_at":"2019-08-28T05:52:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/contentco/angular-match-media","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contentco%2Fangular-match-media","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contentco%2Fangular-match-media/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contentco%2Fangular-match-media/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contentco%2Fangular-match-media/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/contentco","download_url":"https://codeload.github.com/contentco/angular-match-media/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234369963,"owners_count":18821358,"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":[],"created_at":"2024-09-25T19:24:16.879Z","updated_at":"2025-09-27T01:30:51.490Z","avatar_url":"https://github.com/contentco.png","language":"JavaScript","readme":"# Angular matchMedia Module\n\nProvides an Angular service that returns true if the current screen width matches or false if not. Uses the screen widths predefined in Twitter Bootstrap 3 or a customized size you define. There is a staic method `is` which checks for a match on page load and a dynamic method `on` which checks for a match and updates the value on window resize.\n\n## Installation\n\nDownload the component via bower:\n```bash\nbower install --save angular-media-queries\n```\n\nInclude AngularJS on the page and then include this script. If possible, include these scripts in the footer of your site before the closing `\u003c/body\u003e` tag.\n```html\n\u003cscript type='text/javascript' src='/static/path/to/angular.min.js'\u003e\u003c/script\u003e\n\u003cscript type='text/javascript' src='/static/path/to/angular-media-queries/match-media.js'\u003e\u003c/script\u003e\n```\n\n## Usage\n\nRequire the `matchMedia` module as a dependency in your app:\n```javascript\nangular.module('myApp', ['matchMedia'])\n```\n\n### In a Controller\n\n#### Get\nUse the service's `get` method to get the name of the currently matching media query rule.\n```javascript\nangular.module('myApp', ['matchMedia'])\n.controller('mainController', ['screenSize', function (screenSize) {\n  console.log('Your screen size at the moment matches the \"'+screenSize.get()+'\" media query rule.');\n}]);\n```\n\n#### Is\nUse the service's `is` method to determine if the screensize matches the given string/array.\n```javascript\nangular.module('myApp', ['matchMedia'])\n.controller('mainController', ['screenSize', function (screenSize) {\n  var data = complicatedChartData;\n\n  //Determine to either perform cpu/network-intensive actions(desktop) or retrieve a small static image(mobile). \n  if (screenSize.is('xs, sm')) {\n    // it's a mobile device so fetch a small image\n    $http.post('/imageGenerator', data)\n    .success(function (response) {\n      document.querySelector('.chart').src = response.chartUrl;\n    });\n  }\n  else {\n    // it's a desktop size so do the complicated calculations and render that\n    document.querySelector('.chart')\n    .appendCanvas()\n    .parseData()\n    .renderCrazyChart();\n  }\n}]);\n```\n\n#### On\nThe callback fed to `.on` will execute on every window resize and takes the truthiness of the media query as its first argument.\nBe careful using this method as `resize` events fire often and can bog down your application if not handled properly.\n - Executes the callback function on window resize with the match truthiness as the first argument.\n - Returns the current match truthiness.\n - Passing $scope as a third parameter is optional, when not passed it will use $rootScope\n\n```javascript\nangular.module('myApp', ['matchMedia'])\n.controller('mainController', ['screenSize', function (screenSize) {\n  $scope.isMobile = screenSize.on('xs, sm', function(isMatch){\n    $scope.isMobile = isMatch;\n  });\n}]);\n```\n\n#### When\nIf you only want the callback to fire while in the correct screensize, use the `when` method.\nBe careful using this method as `resize` events fire often and can bog down your application if not handled properly.\n```javascript\nangular.module('myApp', ['matchMedia'])\n.controller('mainController', ['screenSize', function (screenSize) {\n\n    // Will fire as long as the screen is size between 768px and 991px\n    screenSize.when('sm', function() {\n        console.log('Your screen size at the moment is between 768px and 991px.');\n    });\n}]);\n```\n\n#### OnChange\nThe callback fed to `.onChange` will execute only when a window resize causes the media query to begin matching or to \nstop matching, and takes the truthiness of the media query as its first argument.\nBe careful using this method as `resize` events fire often and can bog down your application if not handled properly.\n - Executes the callback function ONLY when the true/false state of the match differs from previous state.\n - Returns the current match truthiness.\n - The 'scope' parameter is required for cleanup reasons (destroy event).\n\n```javascript\nangular.module('myApp', ['matchMedia'])\n.controller('mainController', ['$scope', 'screenSize', function ($scope, screenSize) {\n  $scope.isMobile = screenSize.onChange($scope, 'xs, sm', function(isMatch){\n    $scope.isMobile = isMatch;\n  });\n}]);\n```\n\n#### OnRuleChange\nThe callback fed to `.onRuleChange` will execute only when a window resize causes the matching media query rule to change, \nand takes the name of the matched rule as its first argument.  Depending on your needs, using this method can be more\nefficient than registering multiple `.onChange` handlers.\nBe careful using this method as `resize` events fire often and can bog down your application if not handled properly.\n - Executes the callback function ONLY when the name of the matched rule differs from previous matched rule.\n - Returns the current rule name.\n - The 'scope' parameter is required for cleanup reasons (destroy event).\n\n```javascript\nangular.module('myApp', ['matchMedia'])\n.controller('mainController', ['$scope', 'screenSize', function ($scope, screenSize) {\n  $scope.screenSizeName = screenSize.onRuleChange($scope, function(ruleName){\n    switch (ruleName) {\n      case 'xs':\n        // do something special\n        break;\n      case 'sm':\n        // do something else special\n        break;\n      default:\n        // do general logic\n        break;\n    }\n  });\n}]);\n```\n\n#### isRetina\nThis will return a boolean to indicate if the current screen is hi-def/retina.\n```javascript\nangular.module('myApp', ['matchMedia'])\n.controller('mainController', ['screenSize', function (screenSize) {\n  $scope.isRetina = screenSize.isRetina;\n}]);\n```\n\n### Filter\n\nOperate on string values with the filter: Have the placeholder sign % replaced by the actual media query rule name.\n\n#### Example:\n```html\n    \u003cdiv\u003e {{'Your screen size is: ' | media }} \"\u003c/div\u003e\n```\n\n#### Example with replace:\n```html\n    \u003cdiv ng-include=\"'/views/_partials/_team_%.html' | media:{ replace: '%' }\"\u003e\u003c/div\u003e\n```\n\n#### Extended example:\n```html\n    \u003cdiv ng-include=\"'/views/_partials/_team_%.html' | media:{ replace: '%', groups: { mobile:['ti','xs','sm'], desktop:['md','lg'] } }\"\u003e\u003c/div\u003e\n```\n\n### ngIf Example\n\nIn your controller you can create variables that correspond to screen sizes. For example add the following to your controller:\n```javascript\n// Using static method `is`\nangular.module('myApp', ['matchMedia'])\n.controller('mainController', ['screenSize', function (screenSize) {\n  $scope.desktop = screenSize.is('md, lg');\n  $scope.mobile = screenSize.is('xs, sm');\n}]);\n\n// Using dynamic method `on`, which will set the variables initially and then update the variable on window resize\n$scope.desktop = screenSize.on('md, lg', function(match){\n    $scope.desktop = match;\n});\n$scope.mobile = screenSize.on('xs, sm', function(match){\n    $scope.mobile = match;\n});\n```\n\nThen in your HTML you can show or hide content using ngIf or similar directives that take an Angular expression:\n```javascript\n\u003cimg ng-if='desktop' ng-src='http://example.com/path/to/giant/image.jpg'\u003e\n```\nThis particular example is great for only loading large, unnecessary images on desktop computers.\n\nNote: It's important if you plan on using screensize.is() in directives to assign its return value to a scoped variable. If you don't, it will only be evaluated once and will not update if the window is resized or if a mobile device is turned sideways.\n\n### Custom Screen Sizes or Media Queries\n\nYou can access and therefore customize the media queries or create your own:\n```javascript\nangular.module('myApp', ['matchMedia'])\n.controller('mainController', ['screenSize', function (screenSize) {\n  screenSize.rules = {\n    retina: 'only screen and (min-device-pixel-ratio: 2), only screen and (min-resolution: 192dpi), only screen and (min-resolution: 2dppx)',\n    superJumbo: '(min-width: 2000px)',\n\n  };\n\n  if (screenSize.is('retina')) {\n    // switch out regular images for hi-dpi ones\n  }\n\n  if (screenSize.is('superJumbo')) {\n    // do something for enormous screens\n  }\n}]);\n```\n\n`screenSize.rules` contains a copy of the default rules initially, so it is straightforward to\nadd to or change the default rules rather than replacing them, if you wish.  Setting\n`screenSize.rules` to `null` will cause `screenSize` to use the default (bootstrap3) rules,\nbut does not make them available as a base for further changes; to restore `screenSize.rules`\nto the default value, use `screenSize.restoreDefaultRules()`\n```javascript\nangular.module('myApp', ['matchMedia'])\n.controller('mainController', ['screenSize', function (screenSize) {\n\n  // this removes the lg media query, causing its screen sizes to be lumped in with md\n  delete screenSize.rules.lg;\n  \n  // this reverts the media queries to the bootstrap3 defaults\n  screenSize.rules = null;\n  \n  // this restores screenSize.rules to the default media query values \n  screenSize.restoreDefaultRules();\n  \n  // this adds a new superJumbo media query, without removing the default rules\n  angular.extend(screenSize.rules, {superJumbo: '(min-width: 2000px)'};\n}]);\n```\n\n## License\n\nThis work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/deed.en_US.\n\n## Contributors\n\n* Module roughly based on https://github.com/chrismatheson/ngMediaFilter\n* Polyfill from https://github.com/paulirish/matchMedia.js/\n* @jacopotarantino\n* @thatmarvin\n* Matthias Max @bitflowertweets\n\n## Todo\n\n* Write tests.\n* Add a simple directive wrapper for ng-if.\n* Add Grunt tasks.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontentco%2Fangular-match-media","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcontentco%2Fangular-match-media","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontentco%2Fangular-match-media/lists"}