Elegant-icons-sass NPM

Elegant Icons Sass

This is the Sass version of the Elegant Themes‘ Elegant Icon Font.

Installation

Install this package:
```
npm install --save elegant-icons-sass
```
Import elegant-icons-sass in your code:
```
@import 'node_modules/elegant-icons-sass/scss/elegant-icons-sass';
```
Or, you can also add node_modules/elegant-icons-sass/scss/ to your sass includePaths and make the import cleaner:
```
@import 'elegant-icons-sass';
```

By default, only the woff and woff2 formats (Why?) of the fonts will be pulled from a CDN (using RawGit). If you want to use different formats and/or local fonts, check the Customization section below.

Usage

To use the icons, you will need their names, which you can find here (right after the unicode reference list).

The unicode references of the above list are meant to be used as data-icon, which the support has been removed in this sass version, because it‘s considered a bad practice due to performance issues. If you wish to use this way, you must define it yourself.
On the list, you will find that almost all icons have an icon_ prefix in their names, which seems to be redundant and unnecessary. In this Sass version, you can omit it (as done in the exemples below), but for backwards compatibility they are still valid selectors for all usage types (mixin, placeholder or class).
By default, the icon will be defined as a ::before pseude-element. If you wish to change this default, check the Customization section below.

As a mixin

Include the mixin in your selector:

.my-selector {
  @include elegant-icon('arrow_up');  
}

You can override the icon's default placement by passing it as a second parameter:

.my-selector {
  @include elegant-icon('question', 'after');  
}

As a placeholder

Extend the your selector with the placeholder:

.my-selector {
  @extend %ei-contacts_alt;
}

When using as a placeholder, the prefix ei- must be used. Check the Customization section below on how to change or remove this prefix.

As a class

If you just want to use it as a class, you MUST ACTIVATE the class generation first (Check the Customization section below on how to activate it.)

After activated, you can simply set the icon class name to your html element:

<span class="ei-plus"></span>

When using as a class, the prefix ei- must be used. Check the Customization section below on how to change or remove this prefix.

Customization

This sass version of the Elegant Icons defines a few defaults, which are considered best practices or common use cases. If you wish to override them, here is how:

The overrides below, must be done BEFORE the import explained in the Step 2 of the Usage section.

Activate class selectors

$ei-generate-classes: true;

// Default value: false

Using a different selector prefix:

$ei-icon-prefix: 'my-prefix-';

// Default value: 'ei-'

If you don‘t want to use a prefix, set it to an empty string: $ei-icon-prefix: '';

Set the icons placement as `::after`:

$ei-default-placement: 'after';

// Default value: 'before'

The $ei-default-placement variable can only be set as 'before' or 'after' which will define it as a ::before or an ::after pseudo-element, respectively.

Using different font formats:

// All formats:
$ei-font-formats: eot woff2 woff ttf svg;

// Default value: woff woff2

You can define any formats combination that you need from the available formats on example list above.

Using local fonts

Activate the local font usage:
```
$ei-use-local-fonts: true;
```
Override the font path variable:
```
// Example:
$ei-font-path: '../assets/fonts/elegant-icons/';

// Default value: '/fonts'
```
Please note that the path above must be relative to the generated CSS file, since it is used as a normal src: url() in an @font-face definition.
(Optionally) change the font file name:
```
$ei-font-filename: 'my-custom-icons-filename';

// Default value: 'ElegantIcons'
```
If you‘re just copying the font files and not renaming them, don‘t override this.
(Optionally) change the font family name:
```
$ei-font-family: 'My-Custom-Icons-Family-Name';

// Default value: 'ElegantIcons'
```
Override only if you somehow wish to have a different font-family name defined to the icons font.

You might need to copy the font files yourself from the node_modules/elegant-icons-sass/fonts folder. You can use your build system of choice for that.