{"id":18300319,"url":"https://github.com/jpdevries/emosvg","last_synced_at":"2025-04-09T09:26:40.647Z","repository":{"id":57224876,"uuid":"74518204","full_name":"jpdevries/emosvg","owner":"jpdevries","description":"🎉😃 Progressively enhanced emoji first iconography pattern and utility","archived":false,"fork":false,"pushed_at":"2016-11-28T22:48:01.000Z","size":1214,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-15T04:03:18.377Z","etag":null,"topics":[],"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/jpdevries.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2016-11-22T22:17:02.000Z","updated_at":"2017-01-31T23:16:27.000Z","dependencies_parsed_at":"2022-08-30T16:00:54.108Z","dependency_job_id":null,"html_url":"https://github.com/jpdevries/emosvg","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/jpdevries%2Femosvg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpdevries%2Femosvg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpdevries%2Femosvg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpdevries%2Femosvg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jpdevries","download_url":"https://codeload.github.com/jpdevries/emosvg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248010596,"owners_count":21032951,"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-11-05T15:12:01.500Z","updated_at":"2025-04-09T09:26:40.608Z","avatar_url":"https://github.com/jpdevries.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# emoSVG 🙄\n*(Ugh)*. Progressively enhanced Emoji\u0026ndash;first iconography pattern and\u0026nbsp;utility.  \n[Test it for\u0026nbsp;yourself](https://jpdevries.github.io/emosvg/test/).\n\n![](http://j4p.us/0r0o071g3Z00/emoSVG.gif)\n\n## 🤔 Why?\nSure, we could initially ship heavy and enhanced icons. But we want to progressively enhance the web. We start working within the limitations of HTML and utilize the interpretive nature of Emoji to **initially deliver a growing and universal iconset that weight\u0026nbsp;0kB**.\n\n### 💅 Progressive Enhancement\n\nThere are several advantages to Emoji:\n - fastest growing\u0026nbsp;\"language\"\n - 0kB cost to ship\u0026nbsp;artwork\n - interpretive\n\nIt's not all fun and games though. Emoji are interpative, meaning your art director might not be comfortable with the lack of control of what sighted users will see. There is no \"pixel perfect\" control with Emoji. They'll look different on different systems. This is where progressive enhancement comes in. If we detect, determine, or assume that it is worth the cost of shipping SVG artwork, we can overwrite our nearly weightless Emoji iconography with SVG\u0026nbsp;icons.\n\nSVG icons can be:\n - animated\n - any number of\u0026nbsp;colors\n - delivered efficiently together as a single\u0026nbsp;sprite\n - art directed with\u0026nbsp;precision\n - styled with CSS\u0026nbsp;Variables\n\nemoSVG will turn your Emoji into SVG graphics if and when you ask it to. To accomplish this, emoSVG needs to know one thing:\n - the SVG graphic you'd like to replace the `span.emoji`\u0026nbsp;with\n\nYour SVG graphic can be a SVG file or part of an SVG\u0026nbsp;sprite.\n\n### 🏋️‍ Weigh In\n`emoSVG.min.js` weights a whopping 881 bytes GZIPed and\u0026nbsp;minified. Whoop\u0026mdash;d\u0026mdash;doo. That's not the point. Remember that the artwork you'll be replacing your Emoji with does way something. Keep that in mind and only pass this cost onto your users when\u0026nbsp;appropriate.\n\n### 🐛 Browser Support\nemoSVG works in modern browsers. With the assistance of polyfills, it supports\u0026nbsp;IE9+.  \n[More on polyfills\u0026nbsp;here](https://github.com/jpdevries/emoSVG/tree/master/dist/polyfill).\n\n## 🕰 When?\nWhen you ship your SVG icons totally up to you. emoSVG just gives you a simple API to turn a `span.emoji` element into the appropriate enhanced markup. We recommend that you enhance Emoji into something else\u0026nbsp;when:\n - no `save-data` header is\u0026nbsp;detected\n - JavaScript is\u0026nbsp;enabled\n - user preferences opt into, or do not opt out of, the costs of enhanced\u0026nbsp;iconography\n\n\n\n## 🛠 Usage\n\nemoSVG is installable via bower or by downloading this\u0026nbsp;repository.\n\n```bower\nbower install emosvg --save\n```\n\nUse Emoji in your HTML. Wrap them in\u0026nbsp;`span.emoji`. Or something else.\u0026nbsp;Whatever.\n```html\n\u003ch1\u003e\n  \u003cspan class=\"emoji\"\u003e🎉\u003c/span\u003e\n  \u0026nbsp;Party! You're invited\u0026nbsp;\n  \u003cspan class=\"dancing emoji\"\u003e💃\u003c/span\u003e\n\u003c/h1\u003e\n```\n\n_To progressively enhance Emoji you'll need to use the `data-emosvg` attribute to specify the path to the icon art. You'll also need a tiny bit of\u0026nbsp;JavaScript._\n\n### 🛍 SVG Use\nEnhance Emoji with an SVG graphic from a sprite. Your graphic will be enhanced with the splendid `\u003cuse\u003e`\u0026nbsp;syntax.\n```html\n\u003ch1\u003e\n  \u003cspan class=\"emoji\" data-emosvg=\"assets/img/fontawesome.svg#bicycle\"\u003e🚲\u003c/span\u003e\n  \u0026nbsp;Biking in Amsterdam\n\u003c/h1\u003e\n```\n\nbecomes:\n```html\n\u003ch1\u003e\n  \u003csvg\u003e\n    \u003cuse xlink:href=\"assets/img/fontawesome.svg#bicycle\"\u003e\u003c/use\u003e\n  \u003c/svg\u003e\n  \u0026nbsp;Biking in Amsterdam\n\u003c/h1\u003e\n```\n\n### 🌗 Replace Emoji with SVG using JavaScript\n\nThen include the `emoSVG.js` or `emoSVG.min.js` script in your\u0026nbsp;page:\n```html\n\u003cscript src=\"assets/js/vendor/emoSVG/emoSVG.js\"\u003e\u003c/script\u003e\n```\n\nAnd finally use the JavaScript API to trigger the progressive\u0026nbsp;enhancement.\n\nYou can enhance Emoji one at a\u0026nbsp;time:\n\n```js\ndocument.addEventListener(\"DOMContentLoaded\", function() {\n  const emoji = document.querySelector('.emoji');\n  emoSVG(emoji);\n});\n```\n\nYou can also enhance any number of Emoji at\u0026nbsp;once:\n\n```js\ndocument.addEventListener(\"DOMContentLoaded\", function() {\n  const emoji = document.querySelectorAll('.emoji');\n  emoSVG(emoji);\n});\n```\n\n### 🌐 Universal Module Definition\nemoSVG is packaged by Webpack as a UMD JavaScript module and can be universally used as\u0026nbsp;such. So you can write your scripts how you want. Whatever.\n\n#### `global`\n```html\n\u003cscript src=\"./assets/js/emosvg.js\"\u003e\u003c/script\u003e\n\u003cscript\u003eemoSVG(emoji);\u003c/script\u003e\n```\n\n#### `require()`\n```js\nconst emoSVG = require('emosvg');\nemoSVG(emoji);\n```\n\n### 💰 Cache Busting\nIn the distributed files you'll find a busted folder that contains unminified and minified versions of emoSVG with a cachebusted filename. We recommend you serve `emosvg.*.*.*.min.js` cachebusted with far future reaching expiry dates in\u0026nbsp;production.\n\n```bash\nls lib/emosvg/\nbusted  emosvg.js  emosvg.min.js  polyfill\n\nls lib/emosvg/busted/\nemosvg.0.0.0.js  emosvg.0.0.0.min.js\n```\n\n### 🎨 SVG Graphic\nEnhance Emoji with a single SVG file. Your graphic will be enhanced with an `\u003cimg\u003e` element unless you specify\u0026nbsp;otherwise.\n```html\n\u003ch1\u003e\n  \u003cspan class=\"emoji\" data-emosvg=\"assets/img/bicycle.svg\"\u003e🚲\u003c/span\u003e\n  \u0026nbsp;Biking in Amsterdam\n\u003c/h1\u003e\n```\n\nbecomes:\n```html\n\u003ch1\u003e\n  \u003cimg src=\"assets/img/bicycle.svg\" alt=\"\"\u003e\n  \u0026nbsp;Biking in Amsterdam\n\u003c/h1\u003e\n```\n\n### 👣 Inline SVG\nArt using the `\u003cimg src=\"art.svg\"\u003e` can not be styled using CSS because it is not part of the document. The SVG Use syntax can be styled, but that is only applicable when you are using a SVG sprite sheet. If you have a single SVG graphic that you'd like to be embed as part of the document set `data-emosvg-inline=\"true\"`.\n\n```html\n\u003ch1\u003e\n  \u003cspan class=\"bomb emoji\" data-emosvg=\"assets/icons/fontawesome/svg/bomb.svg\" data-emosvg-inline=\"true\"\u003e💣\u003c/span\u003e\n  \u0026nbsp;Da bomb\n\u003c/h1\u003e\n```\n\nbecomes\n\n```html\n\u003ch1\u003e\n  \u003csvg width=\"2048\" height=\"2048\" viewBox=\"0 0 2048 2048\" xmlns=\"http://www.w3.org/2000/svg\"\u003e\u003cpath id=\"icon-bomb\" d=\"M699 717q-10-25-34-35t-49 0q-108 44-191 127t-127 191q-10 25 0 49t35 34q13 5 24 5 42 0 60-40 34-84 98.5-148.5t148.5-98.5q25-11 35-35t0-49zm942-356l46 46-244 243 68 68q19 19 19 45.5t-19 45.5l-64 64q89 161 89 343 0 143-55.5 273.5t-150 225-225 150-273.5 55.5-273.5-55.5-225-150-150-225-55.5-273.5 55.5-273.5 150-225 225-150 273.5-55.5q182 0 343 89l64-64q19-19 45.5-19t45.5 19l68 68zm8-56q-10 10-22 10-13 0-23-10l-91-90q-9-10-9-23t9-23q10-9 23-9t23 9l90 91q10 9 10 22.5t-10 22.5zm230 230q-11 9-23 9t-23-9l-90-91q-10-9-10-22.5t10-22.5q9-10 22.5-10t22.5 10l91 90q9 10 9 23t-9 23zm41-183q0 14-9 23t-23 9h-96q-14 0-23-9t-9-23 9-23 23-9h96q14 0 23 9t9 23zm-192-192v96q0 14-9 23t-23 9-23-9-9-23v-96q0-14 9-23t23-9 23 9 9 23zm151 55l-91 90q-10 10-22 10-13 0-23-10-10-9-10-22.5t10-22.5l90-91q10-9 23-9t23 9q9 10 9 23t-9 23z\"\u003e\u003c/path\u003e\u003c/svg\u003e\n  \u0026nbsp;Da bomb\n\u003c/h1\u003e\n```\n\nNow that the SVG is part of the document it can be further art\u0026nbsp;directed.\n\n_Inline SVG relies on the Fetch API so make sure you polyfill it if necessary before loadin\u0026nbsp; emoSVG._\n\nInlining SVG is an async action as a fetch() request must be made to load the artwork. emoSVG promises to let you know when that is\u0026nbsp;done:\n\n```js\nemoSVG(emoji).then(function() {\n  console.log('inline SVGs loaded');\n  svg4everybody();\n});\n```\n\n### 👾 Raster Graphics\nScalable Vector Graphics are all the rage, but emoSVG understands you may want to get your bitmap\u0026nbsp;on.\n\n```html\n\u003ch1\u003e\n  \u003cspan class=\"emoji\" data-emosvg=\"assets/img/bicycle.png\"\u003e🚲\u003c/span\u003e\u0026nbsp;Biking in Amsterdam\n\u003c/h1\u003e\n```\n\nbecomes:\n```html\n\u003ch1\u003e\n  \u003cimg src=\"assets/img/bicycle.png\" alt=\"\" /\u003e\u0026nbsp;Biking in Amsterdam\n\u003c/h1\u003e\n```\n\nFeel free to use any rasterized graphic you like. File extensions other than SVG will be treated as raster\u0026nbsp;graphics.\n\n### 🐣 Sizing SVG Icons\nEmoji will be sized relative to the text they surround. If you want to make sure your SVG icons aren't oversized in the absense of CSS styles, set the `style` or `data-emojisvg-style` attributes on your `span.emoji`. emoSVG will look for the `style` attribute and then if not found the `data-emojisvg-style` attribute and if found will set the `style` attribute on the\u0026nbsp;`svg.emoji`.\n\n```html\n\u003ch1\u003e\n  \u003cspan class=\"emoji\" data-emosvg=\"assets/img/bicycle.svg\" style=\"width:1em;height:1em\"\u003e🚲\u003c/span\u003e\u0026nbsp;Biking in Amsterdam\n\u003c/h1\u003e\n```\n\nbecomes:\n```html\n\u003ch1\u003e\n  \u003cimg src=\"assets/img/bicycle.png\" style=\"width:1em;height:1em\" /\u003e\u0026nbsp;Biking in Amsterdam\n\u003c/h1\u003e\n```\n\n### 😎 Hiding Icons from Screen Readers\n\nEmoji are implicitly accessible! There is no need to add alt text or labels. If you'd like to use Emoji strictly visually and hide them from screen readers use the `aria-hidden`\u0026nbsp;attribute.\n\n```html\n\u003ch1\u003e\n  \u003cspan class=\"emoji\" data-emosvg=\"assets/img/party.svg\" aria-hidden\u003e🎉\u003c/span\u003e\n  \u0026nbsp;Party! You're invited\u0026nbsp;\n\u003c/h1\u003e\n```\n\n#### 👻 ARIA Hidden\nPlease note that if the `aria-hidden` attribute exists and is set to anything other than false the enhanced graphic will inherit the `aria-hidden` attribute\u0026nbsp;value.\n\n```html\n\u003ch1\u003e\n  \u003cspan class=\"emoji\" data-emosvg=\"assets/img/fontawesome.svg#bicycle\" aria-hidden=\"true\"\u003e🚲\u003c/span\u003e\n  \u0026nbsp;Biking in Amsterdam\n\u003c/h1\u003e\n```\n\nbecomes:\n```html\n\u003ch1\u003e\n  \u003csvg aria-hidden=\"true\"\u003e\n    \u003cuse xlink:href=\"assets/img/fontawesome.svg#bicycle\"\u003e\u003c/use\u003e\n  \u003c/svg\u003e\n  \u0026nbsp;Biking in Amsterdam\n\u003c/h1\u003e\n```\n\n\n### 📣 Describing Enhaned Icons\n\nIf you'd like to describe the SVG icon the `data-emosvg-alt` attribute has your back. If you are making use of `\u003ctitle\u003e` in your SVG code this may be\u0026nbsp;unecessary.\n\n```html\n\u003ch1\u003e\n  \u003cspan class=\"emoji\" data-emosvg=\"assets/img/fontawesome.svg#bicycle\" data-emosvg-alt=\"Graphic of a commuter bicycle\"\u003e🚲\u003c/span\u003e\n  \u0026nbsp;Biking in Amsterdam\n\u003c/h1\u003e\n```\n\nbecomes:\n```html\n\u003ch1\u003e\n  \u003csvg\u003e\n    \u003ctitle\u003eGraphic of a commuter bicycle\u003c/title\u003e\n    \u003cuse xlink:href=\"assets/img/fontawesome.svg#bicycle\"\u003e\u003c/use\u003e\n  \u003c/svg\u003e\n  \u0026nbsp;Biking in Amsterdam\n\u003c/h1\u003e\n```\n\nand likewise this:\n```html\n\u003ch1\u003e\n  \u003cspan class=\"emoji\" data-emosvg=\"assets/img/bicycle.png\" data-emosvg-alt=\"Raster icon of an old blue bike\"\u003e🚲\u003c/span\u003e\u0026nbsp;Biking in Amsterdam\n\u003c/h1\u003e\n```\n\nbecomes:\n```html\n\u003ch1\u003e\n  \u003cimg src=\"assets/img/bicycle.svg\" alt=\"Raster icon of an old blue bike\"\u003e\n  \u0026nbsp;Biking in Amsterdam\n\u003c/h1\u003e\n```\n\n### Undo/Redo Support\nemoSVG lets you switch back and forth from interpretive Emoji icons to declarative art directed\u0026nbsp;icons.  \nWhatever.\n\nJust call `emoSVG(document.querySelectorAll('.emoji'))` and all your icons will be toggled between Emoji and declarative\u0026nbsp;icons.\n\nThis is useful for offering an Accessibility Preferences component that allows users freedom of choice. Remember saving bandwidth isn't the only advantage to Emoji icon sets. To certain users, Emoji icons may be more legible than declarative\u0026nbsp;icons.\n\n![](http://j4p.us/2x422N2l373K/emojiprefs.gif)\n\n## Getting Started\nAfter cloning the repository run `npm install` or `yarn` to install the `node_modules`. You can then build and test the\u0026nbsp;project.\n\nOptionally enable Growl notifications install [terminal-notifier](https://github.com/alextucker/grunt-growl#getting-started) with RubyGems:\n```bash\ngem install terminal-notifier\n```\n_Note: Depending on your Ruby setup you may need to use `sudo gem install terminal-notifier`._\n\n### Test emoSVG\n```bash\ngrunt test\n```\n\n### Build emoSVG\n```bash\ngrunt build\n```\n\n### Watch emoSVG\n```bash\ngrunt watch #watches source files in _build/js for changes and build files\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpdevries%2Femosvg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjpdevries%2Femosvg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpdevries%2Femosvg/lists"}