selectic/doc/changeIcons.md

Smart Select for VueJS 3.x

# Change icons

[Back to documentation index](main.md)

There are some icons in selectic. But sometimes it is useful to change them (because you want to use yours or the same of your favorite theme).

There are 3 ways to changes these icons:
* Call the static `changeIcons(icons, iconFamily)` method. It changes icons for all selectic components.
* Change the `icons` property. It changes icons only for the component.
* Change the `iconFamily` property. It changes the icons origin only for the component.
* Call the `changeIcons(icons, iconFamily)` method on the component. It changes icons only for the component.

_Changes made locally take precedence over changes made globally_.

Changing `icons` or `iconFamily` on the component with property or with `changeIcons()` are equivalent.

`icons` and the first argument of `changeIcons` accept the same kind of value: an object which contains icon keys and how to display them.

It is possible to replace only some icons.

`iconFamily` and the second argument of `changeIcons` accept a string describing how to display icons.

## Icon family

* **selectic** _(default)_: use the internal icons

* **raw**: will create a span with the icon key as class (without any other prefix)

* **font-awesome-4**: will create a span with font-awesome (v4) class.
_Font-awesome is not include in Selectic, your project should have it_.

* **font-awesome-5**: will create a span with font-awesome (v5) class.
_Font-awesome is not include in Selectic, your project should have it_.

* **font-awesome-6**: will create a span with font-awesome (v6) class.
_Font-awesome is not include in Selectic, your project should have it_.

* **prefix:_[string]_**: will create a span and will add the given string as class before the icon key.

Example:
```html
<Selectic iconFamily="prefix:my-icon-" />
```
The icon `search` will be displayed like this:
```html
<span class="my-icon-search"></span>
```

## Icon Keys

* **caret-down**: indicates that menu or panel could be extended down.
* **caret-up**: indicates that panel could be collapsed upward.
* **check**: indicates that the item is currently selected.
* **search**: indicates the search bar.
* **spinner**: indicates that we are fetching data.
* **strikethrough**: indicates that we are in reverse selection mode.
* **times**: used to clear the current selection.
* **question**: used when the icon key is not found. _It should be never displayed._

* **spin**: additional class added to rotate the current icon (used mainly with spinner).

The value indicates what should be used instead of the icon key.

It is possible to use `selectic:` prefix to display the original selectic icon, even if the icon family is configured differently.

It is possible to use `raw:` prefix to display an icon with a span and only the given class (with no prefix).

In some case, the prefix `current:` could be used to use the current icon family.


With `selectic:`, `raw:`, or `current:` prefix, it is also possible to add a `:spin` suffix in order to add the _spin_ on the icon.

Example:
```javascript
{
    spinner: 'selectic:spinner:spin', // it will use the Selectic's spinner icon with the spin effect
    search: 'current:cogs:spin', // it will use "cogs" as key in the current icon family, and will adds the spin effect
}
```

## Example

```javascript
// change icons for all selectic components
Selectic.changeIcons({
    times: 'trash',
    spinner: 'selectic:spinner',
}, 'font-awesome-6');

/* The icon 'times' will be displayed:
 *     <span class="fa-solid fa-trash"></span>
 *
 * The icon 'spinner' will use the selectic's spinner icon.
 */

// change texts only for this instance
this.$refs.selectic.changeIcons({
    'caret-up': 'caret-down',
});
/* For this selectic instance,
 * the caret-down icon will be displayed when it should be the caret-up.
 * (caret-down will still be used for caret-down)
 */

```

```html
<Selectic
    :icons="{
        check: 'thumbs-o-up',
    }"
    iconFamily="font-awesome-4"
/>

/* For this selectic instance, the selected icon will be displayed:
 * <span class="fa fa-thumbs-o-up"></span>
 */
```

It is possible to change only the icon family:
```javascript
// change icons for all selectic components to use FA-6 icons
Selectic.changeIcons(null, 'font-awesome-6');
```