1 | <p align="center">
|
2 | <a href="https://svgjar.web.app" target="_blank">
|
3 | <img src="https://svgjar.web.app/images/logo-96eaca43925f5d648acc8193b1b9ddd7.svg" alt="Logo">
|
4 | </a>
|
5 | </p>
|
6 |
|
7 | <h3 align="center">
|
8 | Best way to use SVG images in Ember apps.
|
9 | </h3>
|
10 |
|
11 | <p align="center">
|
12 | <a href="https://svgjar-demo.web.app" target="_blank">🎮 View Live Demo</a>
|
13 | ·
|
14 | <a href="https://github.com/voltidev/ember-svg-jar/issues/new?template=---bug-report.md">🐞 Report Bug</a>
|
15 | ·
|
16 | <a href="https://github.com/voltidev/ember-svg-jar/issues/new?template=---feature-request.md">🍩 Request Feature</a>
|
17 | ·
|
18 | <a href="https://github.com/voltidev/ember-svg-jar/issues/new?template=---question.md">🤔 Ask Question</a>
|
19 | </p>
|
20 |
|
21 | <p align="center">
|
22 | <a href="https://github.com/voltidev/ember-svg-jar/actions?query=workflow%3ATest" target="_blank">
|
23 | <img src="https://github.com/voltidev/ember-svg-jar/workflows/Test/badge.svg?branch=master"
|
24 | alt="Build Status">
|
25 | </a>
|
26 | <a href="https://www.npmjs.com/package/ember-svg-jar" target="_blank">
|
27 | <img src="https://img.shields.io/npm/v/ember-svg-jar.svg?color=informational" />
|
28 | </a>
|
29 | <a href="https://www.npmjs.com/package/ember-svg-jar" target="_blank">
|
30 | <img src="https://img.shields.io/npm/dm/ember-svg-jar.svg?color=informational" />
|
31 | </a>
|
32 | <a href="http://emberobserver.com/addons/ember-svg-jar" target="_blank">
|
33 | <img src="http://emberobserver.com/badges/ember-svg-jar.svg" alt="Ember Observer Score">
|
34 | </a>
|
35 | </p>
|
36 |
|
37 | ![](https://svgjar.web.app/images/app-screenshot-adb77f291ccaf5251e42c31eb3b5ddd3.png)
|
38 |
|
39 | ## Table of Contents
|
40 |
|
41 | - [🍩 Features](#-features)
|
42 | - [👋 Getting started](#-getting-started)
|
43 | - [🎮 Usage](#-usage)
|
44 | - [🔧 Configuration](#-configuration)
|
45 | - [❓ FAQ](#-faq)
|
46 | - [👓 Compatibility](#-compatibility)
|
47 | - [💟 Contributors](#-contributors)
|
48 | - [🆓 License](#-license)
|
49 |
|
50 | ## 🍩 Features
|
51 |
|
52 | Here's some of useful features:
|
53 |
|
54 | - <a href="https://svgjar-demo.web.app" target="_blank">Visual workflow</a> to find and use SVGs the fastest way possible
|
55 | - Automatic SVG optimization (it can cut file size by half or more)
|
56 | - Easy to use helper `{{svg-jar "asset-name"}}`
|
57 | - Support for both `inline` and `symbol` embedding methods
|
58 | - Copy SVG as CSS background
|
59 | - Zero configuration
|
60 |
|
61 | ## 👋 Getting started
|
62 |
|
63 | **Installation**
|
64 |
|
65 | `$ ember install ember-svg-jar`
|
66 |
|
67 | **Start in 3 easy steps**
|
68 |
|
69 | - 1️⃣ Drop some SVG images to the `public` directory (e.g. [material-design-icons](https://github.com/google/material-design-icons))
|
70 |
|
71 | - 2️⃣ Open the [asset viewer](http://localhost:4200/ember-svg-jar/index.html) and select any icon you like
|
72 |
|
73 | - 3️⃣ Copy the helper code from the viewer and paste it to your template
|
74 |
|
75 | ## 🎮 Usage
|
76 |
|
77 | Place your SVG images to the `public` directory (e.g. `./public/images/my-icon.svg`). Then copy the helper code for your image from the [asset viewer](http://localhost:4200/ember-svg-jar/index.html) or just write it by hand like this: `{{svg-jar "my-icon"}}`.
|
78 |
|
79 | The viewer is available at: <a href="http://localhost:4200/ember-svg-jar/index.html" target="_blank">http://localhost:4200/ember-svg-jar/index.html</a>
|
80 |
|
81 | If your `rootURL` is not `/`, then to use the asset viewer you will need to add `rootURL` to the addon [config](https://github.com/voltidev/ember-svg-jar/blob/master/docs/configuration.md#global-options).
|
82 |
|
83 | ### Helper
|
84 |
|
85 | Use the `svg-jar` helper to embed SVG images to your application's templates.
|
86 |
|
87 | For the default `inline` embedding strategy you can write:
|
88 |
|
89 | ```handlebars
|
90 | {{svg-jar 'my-cool-icon' class='icon' width='24px'}}
|
91 | ```
|
92 |
|
93 | The helper takes an asset ID and optional attributes that will be added to the created SVG element. The example above will create an SVG like this:
|
94 |
|
95 | ```handlebars
|
96 | <svg class='icon' width='24px'>...</svg>
|
97 | ```
|
98 |
|
99 | For the `symbol` strategy you will need to add `#` to the asset ID like this:
|
100 |
|
101 | ```handlebars
|
102 | {{svg-jar '#my-cool-icon'}}
|
103 | ```
|
104 |
|
105 | In this case the result can look like this:
|
106 |
|
107 | ```handlebars
|
108 | <svg><use xlink:href='#my-cool-icon'></use></svg>
|
109 | ```
|
110 |
|
111 | ### Accessibility
|
112 |
|
113 | Pass `title`, `desc`, and `role` as properties to the helper in order to include accessible elements or attributes. `aria-labelledby` will be automatically added and point to `title` and/or `desc` if they are included.
|
114 |
|
115 | Writing this:
|
116 |
|
117 | ```handlebars
|
118 | {{svg-jar 'my-cool-icon' role='img' title='Icon' desc='A very cool icon'}}
|
119 | ```
|
120 |
|
121 | Will create an SVG that looks like this:
|
122 |
|
123 | ```handlebars
|
124 | <svg role="img" aria-labelledby="title desc">
|
125 | <title id="title">Icon</title>
|
126 | <desc id="desc">A very cool icon<desc>
|
127 | </svg>
|
128 | ```
|
129 |
|
130 | ### Assets from Node modules
|
131 |
|
132 | By default `ember-svg-jar` looks for SVGs in the `public` directory. To get SVGs from `node_modules` packages or any other directory you will need to add them to `ember-cli-build.js` like this:
|
133 |
|
134 | ```js
|
135 | var app = new EmberApp(defaults, {
|
136 | svgJar: {
|
137 | sourceDirs: [
|
138 | 'node_modules/material-design-icons/file/svg/design',
|
139 | 'node_modules/material-design-icons/action/svg/design',
|
140 | 'public/images/icons',
|
141 | ],
|
142 | },
|
143 | });
|
144 | ```
|
145 |
|
146 | [Click here for more configuration options](#configuration)
|
147 |
|
148 | ### Usage in an addon
|
149 |
|
150 | Using `ember-svg-jar` in an addon is the same as in an app, except that in the `package.json`
|
151 | of the addon, it should be listed as one of the `dependencies` and not `devDependencies`.
|
152 |
|
153 | ## 🔧 Configuration
|
154 |
|
155 | The addon should be useful without any configuration. But it wants to be very configurable when it's time to adjust it for your needs.
|
156 |
|
157 | - [All configuration options](docs/configuration.md)
|
158 | - [Advanced usage examples](docs/examples.md)
|
159 |
|
160 | ## ❓ FAQ
|
161 |
|
162 | **Q:** `Will the asset viewer affect my production build size?`
|
163 | **A:** No, it won't at all. The asset viewer is included in development mode only.
|
164 |
|
165 | **Q:** `Can it find SVG icons outside of the public directory, e.g. from node_modules?`
|
166 | **A:** Yes, it can import SVGs from any directory defined in the sourceDirs array.
|
167 |
|
168 | **Q:** `Why the SVG files deployed into the dist/assets folder without being fingerprinted?`
|
169 | **A:** This is done with the default ember cli behaviour. For more information see [SVG Fingerprinting](docs/svg-fingerprinting.md).
|
170 |
|
171 | **Q:** `Why does this matter?`
|
172 |
|
173 | - [Why GitHub switched from an icon font to SVG](https://github.com/blog/2112-delivering-octicons-with-svg)
|
174 | - ["Inline SVG vs icon fonts" from css-tricks](https://css-tricks.com/icon-fonts-vs-svg/)
|
175 | - [Ten reasons to switch from an icon font to SVG](http://ianfeather.co.uk/ten-reasons-we-switched-from-an-icon-font-to-svg/)
|
176 |
|
177 | **Q:** `Why would you switch from Font Awesome to SVG?`
|
178 |
|
179 | - original Font Awesome is about `149 KB` as TTF and `88.3 KB` as WOFF
|
180 | - it includes `634` icons and you need just some of them usually
|
181 | - 20 Font Awesome icons in SVGJar will be about 4.3 KB (you save `84 KB` or `145 KB` as TTF)
|
182 | - 50 Font Awesome icons in SVGJar will be about `9 KB`
|
183 |
|
184 | You can get Font Awesome icons as individual SVG files from [font-awesome-svg](https://github.com/voltidev/font-awesome-svg).
|
185 |
|
186 | ## 👓 Compatibility
|
187 |
|
188 | Latest ember-svg-jar currently supports:
|
189 |
|
190 | - Ember.js v3.20 or above
|
191 | - Ember CLI v3.20 or above
|
192 | - Node.js v12 or above
|
193 |
|
194 | ## 💟 Contributors
|
195 |
|
196 | Contributions of any kind welcome! See the [Contributing](CONTRIBUTING.md) guide for details.
|
197 |
|
198 | Thanks goes to these wonderful people:
|
199 |
|
200 |
|
201 |
|
202 |
|
203 | <table>
|
204 | <tr>
|
205 | <td align="center"><a href="https://volti.dev/"><img src="https://avatars.githubusercontent.com/u/1476221?v=4" width="100px;" alt=""/><br /><sub><b>Ivan Volti</b></sub></a></td>
|
206 | <td align="center"><a href="https://github.com/jherdman"><img src="https://avatars.githubusercontent.com/u/3300?v=4" width="100px;" alt=""/><br /><sub><b>James Herdman</b></sub></a></td>
|
207 | <td align="center"><a href="http://eaf4.com"><img src="https://avatars0.githubusercontent.com/u/319282?v=4" width="100px;" alt=""/><br /><sub><b>Edward Faulkner</b></sub></a></td>
|
208 | <td align="center"><a href="https://github.com/Turbo87"><img src="https://avatars2.githubusercontent.com/u/141300?v=4" width="100px;" alt=""/><br /><sub><b>Tobias Bieniek</b></sub></a></td>
|
209 | <td align="center"><a href="https://shipshape.io"><img src="https://avatars3.githubusercontent.com/u/2640861?v=4" width="100px;" alt=""/><br /><sub><b>Robert Wagner</b></sub></a></td>
|
210 | <td align="center"><a href="https://github.com/wagenet"><img src="https://avatars3.githubusercontent.com/u/9835?v=4" width="100px;" alt=""/><br /><sub><b>Peter Wagenet</b></sub></a></td>
|
211 | <td align="center"><a href="https://github.com/ryanpatrickcook"><img src="https://avatars2.githubusercontent.com/u/3067243?v=4" width="100px;" alt=""/><br /><sub><b>Ryan Cook</b></sub></a></td>
|
212 | </tr>
|
213 | <tr>
|
214 | <td align="center"><a href="https://github.com/mupkoo"><img src="https://avatars0.githubusercontent.com/u/1788571?v=4" width="100px;" alt=""/><br /><sub><b>Mirko Akov</b></sub></a></td>
|
215 | <td align="center"><a href="http://mrloop.com"><img src="https://avatars3.githubusercontent.com/u/12345?v=4" width="100px;" alt=""/><br /><sub><b>Ewan McDougall</b></sub></a></td>
|
216 | <td align="center"><a href="https://github.com/markcatley"><img src="https://avatars0.githubusercontent.com/u/5198?v=4" width="100px;" alt=""/><br /><sub><b>Mark Catley</b></sub></a></td>
|
217 | <td align="center"><a href="http://www.seated.com"><img src="https://avatars1.githubusercontent.com/u/19490?v=4" width="100px;" alt=""/><br /><sub><b>John Griffin</b></sub></a></td>
|
218 | <td align="center"><a href="http://www.facebook.com/lucin.ivan"><img src="https://avatars3.githubusercontent.com/u/4481706?v=4" width="100px;" alt=""/><br /><sub><b>Ivan Lučin</b></sub></a></td>
|
219 | <td align="center"><a href="https://hyjk2000.github.io"><img src="https://avatars1.githubusercontent.com/u/4647136?v=4" width="100px;" alt=""/><br /><sub><b>James Shih</b></sub></a></td>
|
220 | <td align="center"><a href="http://seg.al"><img src="https://avatars1.githubusercontent.com/u/3156114?v=4" width="100px;" alt=""/><br /><sub><b>djsegal</b></sub></a></td>
|
221 | </tr>
|
222 | <tr>
|
223 | <td align="center"><a href="https://jan.buschtoens.me"><img src="https://avatars0.githubusercontent.com/u/834636?v=4" width="100px;" alt=""/><br /><sub><b>Jan Buschtöns</b></sub></a></td>
|
224 | <td align="center"><a href="https://siva.dev"><img src="https://avatars1.githubusercontent.com/u/7725225?v=4" width="100px;" alt=""/><br /><sub><b>Sivasubramanyam A</b></sub></a></td>
|
225 | <td align="center"><a href="https://alexdiliberto.com"><img src="https://avatars0.githubusercontent.com/u/666459?v=4" width="100px;" alt=""/><br /><sub><b>Alex DiLiberto</b></sub></a></td>
|
226 | <td align="center"><a href="https://github.com/Dhaulagiri"><img src="https://avatars1.githubusercontent.com/u/1672302?v=4" width="100px;" alt=""/><br /><sub><b>Brian Runnells</b></sub></a></td>
|
227 | <td align="center"><a href="https://jenweber.github.io/portfolio/"><img src="https://avatars1.githubusercontent.com/u/16627268?v=4" width="100px;" alt=""/><br /><sub><b>Jen Weber</b></sub></a></td>
|
228 | <td align="center"><a href="http://hakilebara.com"><img src="https://avatars2.githubusercontent.com/u/1991564?v=4" width="100px;" alt=""/><br /><sub><b>Frédéric Soumaré</b></sub></a></td>
|
229 | <td align="center"><a href="http://kiwiupover.com"><img src="https://avatars3.githubusercontent.com/u/647691?v=4" width="100px;" alt=""/><br /><sub><b>David Laird</b></sub></a></td>
|
230 | </tr>
|
231 | <tr>
|
232 | <td align="center"><a href="http://www.lumialabs.com"><img src="https://avatars2.githubusercontent.com/u/533152?v=4" width="100px;" alt=""/><br /><sub><b>Daan van Etten</b></sub></a></td>
|
233 | <td align="center"><a href="https://github.com/tcjr"><img src="https://avatars3.githubusercontent.com/u/142243?v=4" width="100px;" alt=""/><br /><sub><b>Tom Carter</b></sub></a></td>
|
234 | <td align="center"><a href="http://summerisgone.com"><img src="https://avatars0.githubusercontent.com/u/106999?v=4" width="100px;" alt=""/><br /><sub><b>Ivan Gromov</b></sub></a></td>
|
235 | <td align="center"><a href="https://github.com/ro0gr"><img src="https://avatars2.githubusercontent.com/u/875361?v=4" width="100px;" alt=""/><br /><sub><b>Ruslan Hrabovyi</b></sub></a></td>
|
236 | <td align="center"><a href="https://alexlafroscia.com"><img src="https://avatars2.githubusercontent.com/u/1645881?v=4" width="100px;" alt=""/><br /><sub><b>Alex LaFroscia</b></sub></a></td>
|
237 | <td align="center"><a href="https://github.com/ljknight"><img src="https://avatars.githubusercontent.com/u/11436149?v=4" width="100px;" alt=""/><br /><sub><b>Laura Knight</b></sub></a></td>
|
238 | <td align="center"><a href="https://betocantu93.com/"><img src="https://avatars.githubusercontent.com/u/9092644?v=4" width="100px;" alt=""/><br /><sub><b>Alberto Cantú Gómez</b></sub></a></td>
|
239 | </tr>
|
240 | <tr>
|
241 | <td align="center"><a href="https://github.com/SergeAstapov"><img src="https://avatars.githubusercontent.com/u/322983?v=4" width="100px;" alt=""/><br /><sub><b>Sergey Astapov</b></sub></a></td>
|
242 | </tr>
|
243 | </table>
|
244 |
|
245 |
|
246 |
|
247 |
|
248 |
|
249 |
|
250 | ## 🆓 License
|
251 |
|
252 | This project is distributed under the MIT license.
|
253 |
|
254 | ---
|
255 |
|
256 | GitHub [@voltidev](https://github.com/voltidev) ·
|
257 | Twitter [@voltidev](https://twitter.com/voltidev)
|