changeIcons.md

Change icons

Back to documentation index

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:

<Selectic iconFamily="prefix:my-icon-" />

The icon search will be displayed like this:

<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:

{
    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

// 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)
 */

<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:

// change icons for all selectic components to use FA-6 icons
Selectic.changeIcons(null, 'font-awesome-6');