https://github.com/jpdevries/emosvg
đđ Progressively enhanced emoji first iconography pattern and utility
https://github.com/jpdevries/emosvg
Last synced: 12 months ago
JSON representation
đđ Progressively enhanced emoji first iconography pattern and utility
- Host: GitHub
- URL: https://github.com/jpdevries/emosvg
- Owner: jpdevries
- License: mit
- Created: 2016-11-22T22:17:02.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2016-11-28T22:48:01.000Z (over 9 years ago)
- Last Synced: 2025-03-15T04:03:18.377Z (about 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 1.16 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# emoSVG đ
*(Ugh)*. Progressively enhanced Emojiâfirst iconography pattern and utility.
[Test it for yourself](https://jpdevries.github.io/emosvg/test/).
## đ¤ Why?
Sure, 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 0kB**.
### đ
Progressive Enhancement
There are several advantages to Emoji:
- fastest growing "language"
- 0kB cost to ship artwork
- interpretive
It'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Â icons.
SVG icons can be:
- animated
- any number of colors
- delivered efficiently together as a single sprite
- art directed with precision
- styled with CSSÂ Variables
emoSVG will turn your Emoji into SVG graphics if and when you ask it to. To accomplish this, emoSVG needs to know one thing:
- the SVG graphic you'd like to replace the `span.emoji`Â with
Your SVG graphic can be a SVG file or part of an SVGÂ sprite.
### đď¸â Weigh In
`emoSVG.min.js` weights a whopping 881 bytes GZIPed and minified. Whoopâdâ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 appropriate.
### đ Browser Support
emoSVG works in modern browsers. With the assistance of polyfills, it supports IE9+.
[More on polyfills here](https://github.com/jpdevries/emoSVG/tree/master/dist/polyfill).
## đ° When?
When 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 when:
- no `save-data` header is detected
- JavaScript is enabled
- user preferences opt into, or do not opt out of, the costs of enhanced iconography
## đ Usage
emoSVG is installable via bower or by downloading this repository.
```bower
bower install emosvg --save
```
Use Emoji in your HTML. Wrap them in `span.emoji`. Or something else. Whatever.
```html
đ
 Party! You're invitedÂ
đ
```
_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 JavaScript._
### đ SVG Use
Enhance Emoji with an SVG graphic from a sprite. Your graphic will be enhanced with the splendid ``Â syntax.
```html
đ˛
 Biking in Amsterdam
```
becomes:
```html
 Biking in Amsterdam
```
### đ Replace Emoji with SVG using JavaScript
Then include the `emoSVG.js` or `emoSVG.min.js` script in your page:
```html
```
And finally use the JavaScript API to trigger the progressive enhancement.
You can enhance Emoji one at a time:
```js
document.addEventListener("DOMContentLoaded", function() {
const emoji = document.querySelector('.emoji');
emoSVG(emoji);
});
```
You can also enhance any number of Emoji at once:
```js
document.addEventListener("DOMContentLoaded", function() {
const emoji = document.querySelectorAll('.emoji');
emoSVG(emoji);
});
```
### đ Universal Module Definition
emoSVG is packaged by Webpack as a UMD JavaScript module and can be universally used as such. So you can write your scripts how you want. Whatever.
#### `global`
```html
emoSVG(emoji);
```
#### `require()`
```js
const emoSVG = require('emosvg');
emoSVG(emoji);
```
### đ° Cache Busting
In 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 production.
```bash
ls lib/emosvg/
busted emosvg.js emosvg.min.js polyfill
ls lib/emosvg/busted/
emosvg.0.0.0.js emosvg.0.0.0.min.js
```
### đ¨ SVG Graphic
Enhance Emoji with a single SVG file. Your graphic will be enhanced with an `![]()
` element unless you specify otherwise.
```html
đ˛
 Biking in Amsterdam
```
becomes:
```html
 Biking in Amsterdam
```
### đŁ Inline SVG
Art using the `
` 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"`.
```html
đŁ
 Da bomb
```
becomes
```html
 Da bomb
```
Now that the SVG is part of the document it can be further art directed.
_Inline SVG relies on the Fetch API so make sure you polyfill it if necessary before loadin emoSVG._
Inlining 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 done:
```js
emoSVG(emoji).then(function() {
console.log('inline SVGs loaded');
svg4everybody();
});
```
### đž Raster Graphics
Scalable Vector Graphics are all the rage, but emoSVG understands you may want to get your bitmap on.
```html
đ˛Â Biking in Amsterdam
```
becomes:
```html
 Biking in Amsterdam
```
Feel free to use any rasterized graphic you like. File extensions other than SVG will be treated as raster graphics.
### đŁ Sizing SVG Icons
Emoji 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 `svg.emoji`.
```html
đ˛Â Biking in Amsterdam
```
becomes:
```html
 Biking in Amsterdam
```
### đ Hiding Icons from Screen Readers
Emoji 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`Â attribute.
```html
đ
 Party! You're invitedÂ
```
#### đť ARIA Hidden
Please 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 value.
```html
đ˛
 Biking in Amsterdam
```
becomes:
```html
 Biking in Amsterdam
```
### đŁ Describing Enhaned Icons
If you'd like to describe the SVG icon the `data-emosvg-alt` attribute has your back. If you are making use of `` in your SVG code this may be unecessary.
```html
đ˛
 Biking in Amsterdam
```
becomes:
```html
Graphic of a commuter bicycle
 Biking in Amsterdam
```
and likewise this:
```html
đ˛Â Biking in Amsterdam
```
becomes:
```html
 Biking in Amsterdam
```
### Undo/Redo Support
emoSVG lets you switch back and forth from interpretive Emoji icons to declarative art directed icons.
Whatever.
Just call `emoSVG(document.querySelectorAll('.emoji'))` and all your icons will be toggled between Emoji and declarative icons.
This 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 icons.
## Getting Started
After cloning the repository run `npm install` or `yarn` to install the `node_modules`. You can then build and test the project.
Optionally enable Growl notifications install [terminal-notifier](https://github.com/alextucker/grunt-growl#getting-started) with RubyGems:
```bash
gem install terminal-notifier
```
_Note: Depending on your Ruby setup you may need to use `sudo gem install terminal-notifier`._
### Test emoSVG
```bash
grunt test
```
### Build emoSVG
```bash
grunt build
```
### Watch emoSVG
```bash
grunt watch #watches source files in _build/js for changes and build files
```