Skip to content

Commit 153d128

Browse files
author
Scott Hyndman
committed
Merge pull request #243 from jpc-ae/spritemap-documentation
SVG symbol sprite documentation & cleanup
2 parents de79291 + 56a0546 commit 153d128

File tree

3 files changed

+126
-41
lines changed

3 files changed

+126
-41
lines changed

‎README.md‎

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Material design icons are the official [icon set](http://www.google.com/design/spec/style/icons.html#icons-system-icons) from Google that are designed under the [material design guidelines](http://www.google.com/design/spec).
44

5-
## 2.1 Update
5+
### 2.1 Update
66

77
The 2.1 update adds 96 new icons!
88

@@ -12,16 +12,27 @@ Check out what's new in the [material icons library](https://www.google.com/desi
1212

1313
Read the [developer guide](http://google.github.io/material-design-icons/) on how to use the material design icons in your project.
1414

15-
## Using sprite sheets
15+
### Using a font collection
1616

17-
In `css-sprite` and `svg-sprite` are pre-generated sprite sheets. Instructions for using them are in the [sprites documentation](https://github.com/google/material-design-icons/tree/master/sprites).
17+
The `iconfont` folder contains pre-generated font files that can be included in a project. This is especially convenient for the web; however, it is generally better to link to the web font hosted on Google Fonts:
18+
19+
```html
20+
<link href="https://fonts.googleapis.com/icon?family=Material+Icons"
21+
rel="stylesheet">
22+
```
23+
24+
Read more in the [font portion](http://google.github.io/material-design-icons/#icon-font-for-the-web) of our full developer guide.
25+
26+
### Using symbols and sprites
27+
28+
The `css-sprite` and `svg-sprite` folders contain pre-generated sprite sheets, as well as svg symbols that can be `<use>`d more directly and with fewer constraints. Instructions for using them are in the [sprites documentation](https://github.com/google/material-design-icons/tree/master/sprites).
1829

1930
## Polymer icons
2031

2132
If you wish to use the icon set with Polymer, we recommend consuming them via the [`<iron-icons>`](https://github.com/polymerelements/iron-icons) element ([`<core-icons>`](https://github.com/Polymer/core-icons) in v0.5).
2233

2334
## License
2435

25-
We have made these icons available for you to incorporate them into your products under the [Creative Common Attribution 4.0 International License (CC-BY 4.0)](http://creativecommons.org/licenses/by/4.0/). Feel free to remix and re-share these icons and documentation in your
26-
products. We'd love attribution in your app's *about* screen, but it's not required. The only thing we ask is that you not re-sell
27-
the icons themselves.
36+
We have made these icons available for you to incorporate them into your products under the [Creative Common Attribution 4.0 International License (CC-BY 4.0)](http://creativecommons.org/licenses/by/4.0/). Feel free to remix and re-share these icons and documentation in your products.
37+
We'd love attribution in your app's *about* screen, but it's not required.
38+
The only thing we ask is that you not re-sell the icons themselves.

‎iconfont/README.md‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,9 @@
1-
The recommended way to use the Material Icons font is hosted by Google Fonts,
2-
available here:
1+
The recommended way to use the Material Icons font is by linking to the web font hosted on Google Fonts:
32

4-
```
3+
```html
54
<link href="https://fonts.googleapis.com/icon?family=Material+Icons"
65
rel="stylesheet">
76
```
87

98
Read more in our full usage guide:
109
http://google.github.io/material-design-icons/#icon-font-for-the-web
11-

‎sprites/README.md‎

Lines changed: 107 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,71 +1,147 @@
11
# Material icon sprites
22

3-
These sprites may not be completely up-to-date, we will update them soon.
3+
Sprite images allow you to use images more efficiently.
4+
Our recommended way to use sprites is to create a single SVG file with the subset of icons needed for the project compiled as symbols.
5+
This will keep the file small and allow for the greatest flexibility in referencing each icon.
6+
It will also allow you to include any other svgs in the project, like a logo, in a single reference file.
7+
8+
Note that symbol files must be `<use>`ed or opened in an editor in order to be viewed, while sprite sheets can be opened and previewed directly.
49

510
## Creating your own sprites
611

7-
Our recommended way to use sprite sheets is to create them with the subset of icons needed for the project. Here are two good options for creating your own CSS and SVG sprites.
12+
While PNG and SVG icon images can be combined manually in an editor, using a processor to combine them automatically and generate any needed companion files is definitely the most convenient.
13+
Here are three good options for creating your own CSS and SVG sprites.
814

9-
* [Sprity](https://www.npmjs.com/package/sprity) (previously css-sprite) for CSS sprites.
10-
* [svg-sprite](https://github.com/jkphl/svg-sprite) for SVG sprites.
15+
* [Sprity](https://www.npmjs.com/package/sprity) (previously css-sprite) for PNG sprites with CSS sprite sheets.
16+
* [svg-sprite](https://www.npmjs.com/package/svg-sprite) for SVG sprites with CSS sprite sheets.
17+
* [svgstore](https://github.com/w0rm/gulp-svgstore) for SVG symbol sprites.
1118

19+
When creating a project, there are many similar and extended processors that can be for compilers such as gulp.
1220

13-
## Using provided sprite sheets
21+
## Using the provided sprites
1422

15-
Material design icons come with SVG and CSS sprites for each category of icon we include. These can be found in the `sprites` directory, under `svg-sprite` and `css-sprite`.
23+
Material design icons come with CSS sprite sheets and SVG symbol sprites for each category of icon we include.
24+
The icon sprites can be found in the `sprites` directory under `css-sprite` for png image sprites and `svg-sprite` for the various svg sprite techniques—including symbols.
25+
Symbol sprites in the `svg-sprite` folder have an additional `-symbol` marker after their name.
26+
If you are considering using svg sprites, you are encouraged to `<use>` the symbol sprites rather than traditional sprite sheets as they reduce the size of the files and the complexity and redundancy of using them.
1627

17-
### Using CSS Sprites
1828

19-
To use a CSS spritesheet, reference the stylesheet for the icon category you wish to use, then include the icon definition in your markup. E.g to use one of the play icons in `css-sprite-av`:
29+
## Using SVG symbol sprites
2030

21-
Reference the stylesheet:
31+
To add an icon using symbol sprites, you will need to add an svg element that `<use>`es the reference file with a link to the specific icon you want.
32+
Since the icons are stored as `<symbol>`s, the viewbox is already set up and can be scaled relatively without needing to keep adjacent symbols in mind. You will only need set the size of the icon using CSS:
2233

23-
```html
24-
<link href="css-sprite/sprite-av-black.css" rel="stylesheet">
34+
```CSS
35+
.svg-24px {
36+
width: 24px;
37+
height: 24px;
38+
}
2539
```
2640

27-
Create an element which will use the icon as a background:
41+
Then reference the id for the icon you need:
2842

29-
```html
30-
<div></div>
43+
```HTML
44+
<svg class="svg-24px">
45+
<use xlink:href="MaterialIcons.svg#ic_face_24px"></use>
46+
</svg>
3147
```
3248

33-
Add a class referencing the `icon` sprite sheet and specific icon `icon-ic_play_circle_outline_black_24dp`, which you can get from the above stylesheet.
49+
The HTML can also be simplified further by targeting all svg tags, and then overriding the size for individual classes and IDs.
50+
While you will need to be careful not to let this hamper your layout, this kind of sizing is generally a matter of course.
51+
To make 24px the default for `<svg>` tags, add the tag properties in css:
3452

35-
```html
36-
<div class="icon icon-ic_play_circle_outline_black_24dp"></div>
53+
```CSS
54+
svg {
55+
width: 24px;
56+
height: 24px;
57+
}
3758
```
3859

39-
That's it!
60+
Then reference the icon:
61+
62+
```HTML
63+
<svg><use xlink:href="MaterialIcons.svg#ic_face_24px"></use></svg>
64+
```
4065

41-
Don't forget to publish the corresponding CSS and SVG/PNG files when deploying your project.
66+
### Stacking symbol sprite icons
4267

43-
### Using SVG Sprites
68+
Using symbol sprites, icons can also easily be stacked on top of each other by including them in a single svg `<use>` statement.
69+
Each icon can then be referenced using ids and classes and likewise handled using javascript.
70+
E.g. To add a blue checkmark on top of a checkbox outline than can then be hidden when needed, first add the fill property in CSS:
71+
72+
```CSS
73+
.svg-24px {
74+
width: 24px;
75+
height: 24px;
76+
}
77+
.check {
78+
fill: blue;
79+
}
80+
```
81+
82+
Then add the check after the outline icon together with an id for the SVG tag (for targeting) and the check class for the checkmark:
83+
84+
```HTML
85+
<svg class="svg-24px" id="checkbox-1">
86+
<use xlink:href="MaterialIcons.svg#ic_check_box_outline_blank"></use>
87+
<use class="check" xlink:href="MaterialIcons.svg#ic_check_box"></use>
88+
</svg>
89+
90+
```
4491

45-
Similarly, to use an SVG sprite sheet, reference the stylesheet for the icon category, then include the icon definition in your markup.
92+
### External SVG symbols
4693

47-
E.g: to use one of the play icons in `svg-sprite-av`, reference the stylesheet:
94+
The benefits to referencing an external svg come in the form of caching, as the same map file can be reused across the site and on subsequent visits.
95+
96+
Unfortunately, Internet Explorer, Edge, and older Android and iOS browsers cannot `<use>` external svg files.
97+
Besides copying the svg file contents directly into each html file you need them in, there are two good ways to handle this:
98+
99+
1. Use the [svg4everybody polyfill](https://github.com/jonathantneal/svg4everybody) (this is the preferred method)
100+
2. Use a simple AJAX call to include the symbol sprites in the document for all browsers, and then reference the svg directly wherever it is `<use>´d rather than the external file
101+
102+
### CSS Selectors, Transformation and the Shadow DOM
103+
104+
For some projects, parts of individual icons may be required to change or animate in some way relative to the icon, rather than as a whole. For example, an icon where the top part flies away or two parts are given separate colors. This is the power given to inline svg, as opposed to a simple image file.
105+
106+
Browser support for the `<use>` element, however, is still not good enough to properly allow the targeting of its shadow DOM. While not impossible, it can make selecting individual paths on a page very tricky.
107+
108+
In projects where individual paths need to be targeted, it is best to copy them inline or inject the paths into the html at build or load time, regardless of browser, to prevent issues that may arise due to the shadow DOM nature of the `<use>` element. There are two ways to handle this depending on the project:
109+
1. The recommended way to do this is automatically using a build script or with a tool like [gulp-inject](https://github.com/klei/gulp-inject) that can reference individual icons, as that will keep the html files small and prevent having to make an href request.
110+
2. If the project is designed to generate all pages dynamically using very few static elements, or none at all, the svg elements can instead be pulled in using javascript ajax calls. In this case, a purely concatenated xml file containing the individual icons required would work better and be easier to target than a symbol map.
111+
112+
## Using CSS sprite sheets
113+
114+
To use a CSS sprite sheet, reference the stylesheet for the icon category you wish to use, then include the icon definition in your markup.
115+
E.g. using one of the play icons in `css-sprite-av`...
116+
117+
Reference the stylesheet:
48118

49119
```html
50-
<link href="svg-sprite/svg-sprite-av.css" rel="stylesheet">
120+
<link href="png/sprite-av-black.css" rel="stylesheet">
51121
```
52122

53-
Create an element which will use the icon as a background:
123+
Create an element which will use the icon as a background, and include that icon as a class.
124+
The example class here references the `icon` sprite sheet and specific `icon-ic_play_circle_outline_black_24dp` icon, which you can get from the above stylesheet.
54125

55126
```html
56-
<div></div>
127+
<div class="icon icon-ic_play_circle_outline_black_24dp"></div>
57128
```
58129

59-
Next, make sure to set a dimension for the icon. This can either be done inline or via a class. We'll use a class for this example:
130+
That's it! Well, for PNG sprites anyway.
131+
132+
If you are using svg sprites by referencing `svg/sprite-av-black.css` in this example instead, you will also need to set a dimension for the icon.
133+
This can either be done inline or via a generic size class or a specific class such as this one:
60134

61135
```html
62-
<style>
63-
.svg-ic_play_circle_outline_24px-dims { width: 24px; height: 24px; }
64-
</style>
136+
<style>
137+
.svg-ic_play_circle_outline_black_24dp-dims { width: 24px; height: 24px; }
138+
</style>
65139
```
66140

67-
Finally, set the dimension and specific icon `svg-ic_play_circle_outline_24px`, which you can get from the above stylesheet.
141+
Then, make sure you set the dimension for the specific icon, `svg-ic_play_circle_outline_black_24dp`, which you can get from the svg stylesheet.
68142

69143
```html
70-
<div class="svg-ic_play_circle_outline_24px svg-ic_play_circle_outline_24px-dims"></div>
144+
<div class="svg-ic_play_circle_outline_black_24dp svg-ic_play_circle_outline_black_24dp-dims"></div>
71145
```
146+
147+
Don't forget to publish the corresponding CSS and SVG/PNG files when deploying your project.

0 commit comments

Comments
 (0)