Skip to content
Permalink
Browse files

feat(docs): svg icons and Quasar svg Icon Sets

  • Loading branch information
rstoenescu committed Jan 11, 2020
1 parent fd260b4 commit b2660df4ca14d07432110196656f77f1f124304b
@@ -485,7 +485,6 @@ const style = [
},
{
name: 'Dark Mode',
badge: 'new',
path: 'dark-mode'
},
{
@@ -609,7 +608,6 @@ const directives = [
},
{
name: 'Intersection',
badge: 'new',
path: 'intersection'
},
{
@@ -618,7 +616,6 @@ const directives = [
},
{
name: 'Mutation',
badge: 'new',
path: 'mutation'
},
{
@@ -670,8 +667,7 @@ const plugins = [
},
{
name: 'Dark',
path: 'dark',
badge: 'new'
path: 'dark'
},
{
name: 'Dialog',
@@ -843,7 +839,6 @@ const components = [
},
{
name: 'Img',
badge: 'update',
path: 'img'
},
{
@@ -856,7 +851,6 @@ const components = [
},
{
name: 'Intersection',
badge: 'new',
path: 'intersection'
},
{
@@ -985,7 +979,6 @@ const components = [
},
{
name: 'Tree',
badge: 'update',
path: 'tree'
},
{
@@ -1061,7 +1054,6 @@ const appExtensions = [
},
{
name: 'Starter kit equivalent',
badge: 'new',
path: 'starter-kit-equivalent'
},
{
@@ -1205,8 +1197,7 @@ module.exports = [
{
name: 'Video Tutorials',
icon: 'ondemand_video',
path: 'video-tutorials',
badge: 'new'
path: 'video-tutorials'
},
{
name: 'Meet the Team',
@@ -6,10 +6,12 @@ related:
- /vue-components/icon
---

**This page refers to using [webfont icons](/vue-components/icon#Webfont-icons) only.** Svg icons do not need any installation step.

You'll most likely want icons in your website/app and Quasar offers an easy way out of the box for the following icon libraries: [Material Icons](https://material.io/icons/) , [Font Awesome](http://fontawesome.io/icons/), [Ionicons](http://ionicons.com/), [MDI](https://materialdesignicons.com/), [Eva Icons](https://akveo.github.io/eva-icons) and [Themify Icons](https://themify.me/themify-icons).

::: tip
You can choose to install one or more of these icon libraries.
In regards to webfont icons, you can choose to install one or more of these icon libraries.
:::

## Installing
@@ -23,7 +25,7 @@ extras: [
]
```

Icon sets are available through [@quasar/extras](https://github.com/quasarframework/quasar/tree/dev/extras) package. You don't need to import it in your app, just configure `/quasar.conf.js` as indicated above.
Webfont icons are available through [@quasar/extras](https://github.com/quasarframework/quasar/tree/dev/extras) package. You don't need to import it in your app, just configure `/quasar.conf.js` as indicated above.

Adding more than one set (showing all options):
```js
@@ -12,15 +12,17 @@ You can install multiple icon libraries, but you must choose only one to use on

Quasar currently supports: [Material Icons](https://material.io/icons/) , [Font Awesome](http://fontawesome.io/icons/), [Ionicons](http://ionicons.com/), [MDI](https://materialdesignicons.com/), [Eva Icons](https://akveo.github.io/eva-icons), and [Themify Icons](https://themify.me/themify-icons).

It is also possible to use your own icons (as images in any format) with any Quasar component, see the [QIcon page](/vue-components/icon#Images-instead-of-webfont) for more info on this.
It is also possible to use your own icons (as custom svgs or as images in any format) with any Quasar component, see the [QIcon](/vue-components/icon#Image-icons) page for more info on this.

::: tip
Related pages: [Installing Icon Libraries](/options/installing-icon-libraries) and [QIcon component](/vue-components/icon).
:::

## Installing a Quasar Icon Set

Unless configured otherwise, Quasar uses Material Icons as its icon set for its components. You can however tell Quasar to use some other icon set, but be sure to include that set in your website/app (see [Installing Icon Libraries](/options/installing-icon-libraries)).
**There are two types of Quasar Icon Sets: webfont-based and svg-based.**

Unless configured otherwise, Quasar uses Material Icons webfont as its icon set for its components. You can however tell Quasar to use some other icon set, but if it's a webfont-based one then be sure to include its icon library in your website/app (see [Installing Icon Libraries](/options/installing-icon-libraries)).

So let's say we included Ionicons and we want Quasar to use it for its components.

@@ -29,10 +31,18 @@ We edit `/quasar.conf.js` again:

```js
framework: {
// webfont-based example
iconSet: 'fontawesome-v5'
}
```

```js
framework: {
// svg-based example
iconSet: 'svg-mdi-v4'
}
```

For all available options, visit the [GitHub](https://github.com/quasarframework/quasar/tree/dev/ui/icon-set) repository.

#### Full Example
@@ -48,7 +58,7 @@ framework: {
}
```

This will enable you to use both Ionicons & Fontawesome in your app, and all Quasar components will display Fontawesome icons.
This will enable you to use both Ionicons & Fontawesome webfonts in your app, and all Quasar components will display Fontawesome icons.

#### Changing Icon Set Dynamically
Quasar Icon Set is reactive, so all components will update properly if you change the $q.iconSet object. Here is an example:
@@ -83,7 +93,7 @@ Include the Quasar Icon Set tag for your Quasar version and also tell Quasar to
</script>
```

Check what tags you need to include in your HTML files by generating a sample with `$ quasar create <folder> --kit umd` and specifying an icon set (other than the default "material-icons").
Check what tags you need to include in your HTML files on [UMD / Standalone](/start/umd) page.


### Vue CLI Way
@@ -9,6 +9,8 @@ related:
The QIcon component allows you to easily insert icons within other components or any other area of your pages.
Quasar currently supports: [Material Icons](https://material.io/icons/) , [Font Awesome](http://fontawesome.io/icons/), [Ionicons](http://ionicons.com/), [MDI](https://materialdesignicons.com/), [Eva Icons](https://akveo.github.io/eva-icons) and [Themify Icons](https://themify.me/themify-icons).

There are multiple types of icons in Quasar: webfont-based, svg-based (v1.7+) and image-based. You are not bound to using only one type in your website/app.

::: tip
Related pages: [Installing Icon Libraries](/options/installing-icon-libraries) and [Quasar Icon Sets](/options/quasar-icon-sets).
:::
@@ -18,16 +20,16 @@ Related pages: [Installing Icon Libraries](/options/installing-icon-libraries) a

## Usage
::: warning
Make sure that you [installed the icon library](/options/installing-icon-libraries) that you are using, otherwise it won't show up!
If you are using webfont-based icons, make sure that you [installed the icon library](/options/installing-icon-libraries) that you are using, otherwise it won't show up!
:::

### Icons name cheatsheet
### Webfont icons

```html
<q-icon name="..." />
```

| Name | Prefix | Examples | Notes |
| Quasar IconSet name | Name prefix | Examples | Notes |
| --- | --- | --- | --- |
| material-icons | *None* | thumb_up | Notice the underline character instead of dash or space |
| material-icons-outlined | o_ | o_thumb_up | Notice the underline character instead of dash or space; **Requires Quasar 1.0.5+** |
@@ -40,22 +42,90 @@ Make sure that you [installed the icon library](/options/installing-icon-librari
| eva-icons | eva- | eva-shield-outline, eva-activity-outline | Notice the use of dash characters |
| themify | ti- | ti-hand-point-up | Notice the use of dash characters |

### Size & colors
All icons are **webfont icons**. This means that you can change size by manipulating `font-size` CSS property. And also, they inherit the current CSS text `color` used.
### Svg icons

<doc-example title="Basic" file="QIcon/Basic" />
<q-badge label="Quasar v1.7.0+" />
<q-badge class="q-ml-sm" label="@quasar/extras v1.4+" />

For `icon` properties on different Quasar components you won't have the means to specify an icon for each platform, but you can achieve the same effect with:
There are many advantages of using only svg icons in your website/app:
* Better app footprint -- only used icons will be included in the final build (treeshaking in action)
* Better quality icons
* No need for including equivalent webfonts from `@quasar/extras` or CDN.

The current disadvantage is that it is more tedious to use these icons than their webfont counterpart.

Notice in the example below that we want to avoid Vue observable wrapping, so we inject icons on the instance through created() hook. It will work if declared in data() too, but... overhead.

```html
<q-btn
:icon="$q.platform.is.ios ? 'settings' : 'ion-ios-gear-outline'"
/>
<template>
<div>
<q-icon :name="matMenu" />
<q-btn :icon="mdiAbTesting" />
</div>
</template>

<script>
import { matMenu } from '@quasar/extras/material-icons'
import { mdiAbTesting } from '@quasar/extras/mdi-v4'
export default {
// ...
created () {
this.matMenu = matMenu
this.mdiAbTesting = mdiAbTesting
}
}
```
<doc-example title="Standard sizes" file="QIcon/StandardSizes" />
::: tip
If you are only using svg icons (and have configured a [Quasar Icon Set](/options/quasar-icon-sets)) then you don't need the webfont equivalent in your app at all.
:::
| Vendor | Quasar IconSet name | Import Icons from |
| --- | --- | --- |
| Material Icons (Google) | svg-material-icons | @quasar/extras/material-icons |
| MDI (Material Design Icons) | svg-mdi-v4 | @quasar/extras/mdi-v4 |
| Font Awesome | svg-fontawesome-v5 | @quasar/extras/fontawesome-v5 |
| Ionicons | svg-ionicons-v4 | @quasar/extras/ionicons-v4 |
| Eva Icons | svg-eva-icons | @quasar/extras/eva-icons |
| Themify Icons | svg-themify | @quasar/extras/themify |
You can also supply your own svg icons. An svg icon is essentially a String with the following syntax:
```
Syntax: "<path>|<viewBox>" or "<path>" (with implicit 0 0 24 24 viewBox)
Examples:
M9 3L5 6.99h3V14h2V6.99h3L9 3zm7 14.01V10h-2v7.01h-3L15 21l4-3.99h-3z|0 0 104 104
M9 3L5 6.99h3V14h2V6.99h3L9 3zm7 14.01V10h-2v7.01h-3L15 21l4-3.99h-3z
// equivalent to the original svg:
<svg viewBox="0 0 104 104">
<path d="M9 3L5 6.99h3V....."/>
</svg>
```
### Inlined svg
<q-badge label="v1.7.0+" />
### Images instead of webfont
QIcon can contain one `<svg>` tag (the content of the svg can be anything, not only a path).
Reasoning on why to use an `<svg>` in a QIcon is that the svg will respect the size and color as any QIcon through its props. Without these features, you're better off inlining the svg in your templates without QIcon.
```html
<q-icon color="accent" size="5rem">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
<path d="M0 0h24v24H0z" fill="none"/>
<path d="M19 3h-4.18C14.4 1.84 13.3 1 12 1c-1.3 0-2.4.84-2.82 2H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2zm-7 0c.55 0 1 .45 1 1s-.45 1-1 1-1-.45-1-1 .45-1 1-1zm0 4c1.66 0 3 1.34 3 3s-1.34 3-3 3-3-1.34-3-3 1.34-3 3-3zm6 12H6v-1.4c0-2 4-3.1 6-3.1s6 1.1 6 3.1V19z"/>
</svg>
</q-icon>
```
Some limitations:
* do not use "height"/"width" attributes on the `<svg>` tag (it will brake QIcon's way of handling the size)
* all `<path>`s will have "fill: currentColor" CSS applied by default; if you don't want that, then add `fill="none"` to the `<path>` tag
### Image icons
You can also make an icon point to an image URL instead of relying on any webfont, by using the `img:` prefix.
**All icon related props of Quasar components can make use of this.**
@@ -93,6 +163,21 @@ You can also base64 encode an image and supply it. The example below is with a Q
img:data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==" ... />
```
### Size & colors
All icons are **webfont icons**. This means that you can change size by manipulating `font-size` CSS property. And also, they inherit the current CSS text `color` used.
<doc-example title="Basic" file="QIcon/Basic" />
For `icon` properties on different Quasar components you won't have the means to specify an icon for each platform, but you can achieve the same effect with:
```html
<q-btn
:icon="$q.platform.is.ios ? 'settings' : 'ion-ios-gear-outline'"
/>
```
<doc-example title="Standard sizes" file="QIcon/StandardSizes" />
### Custom mapping
<q-badge label="v1.4.0+" />
@@ -17,9 +17,9 @@ Why this package? Because it strips down unnecessary package files (so faster do
Please make sure you have latest `@quasar/extras` npm package version installed into your project folder in order for you to benefit from everything below.
### Webfonts:
### Webfonts
| Package | Version | quasar.conf.js extras name | Description | Notes | License |
| Vendor | Version | quasar.conf.js extras name | Description | Notes | License |
| --- | --- | --- | --- | --- | --- |
| Roboto Font | CDN v19 | `roboto-font` | Recommended font along Material theme | | [License](roboto-font/LICENSE) |
| Roboto Font Latin Extended | CDN v19 | `roboto-font-latin-ext` | Recommended font along Material theme | | [License](roboto-font-latin-ext/LICENSE) |
@@ -41,7 +41,7 @@ Please make sure you have latest `@quasar/extras` npm package version installed
> Quasar v1.7+ required for svg Quasar Icon Sets.
| Package | Version | Quasar IconSet name | Import Icons from | Notes | License |
| Vendor | Version | Quasar IconSet name | Import Icons from | Notes | License |
| --- | --- | --- | --- | --- | --- |
| [Material Icons](https://material.io/tools/icons/?style=baseline) (Google) | 3.0.1 | `svg-material-icons` | `@quasar/extras/material-icons` | The svgs are 3 years old! | [License](material-icons/LICENSE) |
| [Material Icons Outlined](https://material.io/tools/icons/?style=outlined) (Google) | | | | *Not yet available* | [License](material-icons-outlined/LICENSE) |

0 comments on commit b2660df

Please sign in to comment.
You can’t perform that action at this time.