Wrapper class

This tutorial is part of Svelte Components for Iconify Icon Finder tutorial.

Wrapper is the main class that creates Icon Finder Core instance, renders container component, manages state and parameters.

It uses callback to notify parent code of any changes (such as new icon was selected or button was clicked) and has several functions that can be used to control Icon Finder instance.

You can import Wrapper class from src/icon-finder/wrapper.ts.

Look in src/icon-finder/index.ts for example:

import { Wrapper } from './wrapper';

const container = document.getElementById('container');
if (container) {
   const wrapper = new Wrapper({
       container,
       callback: (event) => {
           console.log('Event:', event);
       },
   });
}

Constructor for Wrapper has only one parameter: object IconFinderWrapperParams that has the following mandatory properties:

  • container, HTMLElement. Container element where Icon Finder instance should be rendered.
  • callback, IconFinderEvent. Callback function that will be called whenever something happens.

Then there are several optional properties:

Callback

Callback is used to notify you on various events.

For more details see callback documentation.

Custom sets

You can use iconSets property to display your custom icons. It can be used to display one or more icon sets. Icon sets can be merged with icon sets retrieved from API or you can choose to display only your icon sets.

Value can be either array of icon sets in IconifyJSON format. It can also be IconFinderCustomSets object, which also contains array of icon sets in IconifyJSON format, but has few extra properties.

Example:

import { Wrapper } from './wrapper';
import type { IconFinderEvent } from './wrapper/events';

// Create instance
const wrapper = new Wrapper({
   container: document.getElementById('icon-finder'),
   callback: (event: IconFinderEvent) => {
       console.log('Event:', event);
   },
   iconSets: [
       {
           prefix: 'test',
           info: {
               name: 'Test',
           },
           icons: {
               // List of icons here
           },
       },
   ],
});

IconFinderCustomSets type

Type IconFinderCustomSets has the following properties:

  • iconSets, IconifyJSON[]. Array of icon sets.
  • info, Record<string, IconifyInfo>. Metadata for icon sets. If icon set already has metadata, this will override data from icon set.
  • provider, string. API provider. If set, all icon sets in iconSets will be treated as if they belong to that API provider.
  • merge, string. Merge method:
    • "only-custom": Icon Finder will display only custom icon sets.
    • "custom-first": Icon Finder will display both custom icon sets and icon sets from Iconify API. Custom sets will be listed first.
    • "custom-last": Icon Finder will display both custom icon sets and icon sets from Iconify API. Custom sets will be listed last.

When displaying both custom and default icon sets, when searching all icon sets, Icon Finder will display results only from default icon sets. Search for custom icon sets will work only when browsing that icon set.

Example above using IconFinderCustomSets:

import { Wrapper } from './wrapper';
import type { IconFinderEvent } from './wrapper/events';

// Create instance
const wrapper = new Wrapper({
   container: document.getElementById('icon-finder'),
   callback: (event: IconFinderEvent) => {
       console.log('Event:', event);
   },
   iconSets: {
       iconSets: [
           {
               prefix: 'test',
               info: {
                   name: 'Test',
               },
               icons: {
                   // List of icons here
               },
           },
       ],
       merge: 'only-custom',
   },
});

Info property

Icon sets must have info property with icon set name. If missing, Icon Finder will not display that icon set.

If your JSON data does not have info property, you must use IconFinderCustomSets object and must include information for icon set in IconFinderCustomSets's info property.

Example:

import { Wrapper } from './wrapper';
import type { IconFinderEvent } from './wrapper/events';

// Create instance
const wrapper = new Wrapper({
   container: document.getElementById('icon-finder'),
   callback: (event: IconFinderEvent) => {
       console.log('Event:', event);
   },
   iconSets: {
       // Icon sets without metadata
       iconSets: [
           {
               prefix: 'test',
               icons: {
                   // List of icons here
               },
           },
       ],
       // Missing metadata for icon sets
       info: {
           // Info for 'test' icon set
           test: {
               title: 'Test',
           },
       },
   },
});

Examples

For usage example, take a look at Material Line Icons website. It uses Icon Finder with iconSets property to display only custom icon set. See src/icon-finder/index.ts of Material Line Icons repository.

Restoring state

State is provided as property in "button" event, triggered when button in footer has been clicked. See callback documentation for details. You can also retrieve current state using wrapper's getState() function.

You can save that state in application's memory or in cookies and use state property of Wrapper constructor to restore state.

import { Wrapper } from './wrapper';
import type { IconFinderEvent } from './wrapper/events';
import type { IconFinderState } from './wrapper/state';

// Get last saved state
let lastSavedState: Partial<IconFinderState>;
if (/* some condition that checks if state is saved */) {
 // Retrieve state from somewhere
 // lastSavedState =
}

// Create instance
const wrapper = new Wrapper({
   container: document.getElementById('icon-finder'),
   callback: (event: IconFinderEvent) => {
       console.log('Event:', event);
   },
   state: lastSavedState,
});

You can also use it to set initial page:

import { Wrapper } from './wrapper';
import type { IconFinderEvent } from './wrapper/events';

// Create instance
const wrapper = new Wrapper({
   container: document.getElementById('icon-finder'),
   callback: (event: IconFinderEvent) => {
       console.log('Event:', event);
   },
   state: {
       // Set Material Design Icons as home route
       config: {
           router: {
               // Option value is a JSON string, so stringify route
               home: JSON.stringify({
                   type: 'collection',
                   params: {
                       prefix: 'mdi',
                   },
               }),
           },
       },
   },
});

Hide and show

You can show and hide UI using functions show() and hide() of wrapper instance.

const wrapper = new Wrapper({
   // ...
});

wrapper.hide();

Get state

Function getState() returns current state in IconFinderState format.

See IconFinderState documentation.

const wrapper = new Wrapper({
   // ...
});

const state = wrapper.getState();

Get status

Function getStatus() returns status of Icon Finder instance as string. Possible values:

  • "" (empty string): default status.
  • "loading": instance is loading.
  • "hidden": instance is hidden.
  • "destroyed": instance has been destroyed.

Destroy

Function destroy() destroys instance. All data stored in memory gets destroyed. Use this function if your UI no longer needs Icon Finder instance.

const wrapper = new Wrapper({
   // ...
});

// Destroy instance
wrapper.destroy();

setRoute

This function changes current route.

This function should not be used to set initial route. You should set initial route using constructor's state.route property. This function should be used to change route after some action, for example a button has been clicked.

const wrapper = new Wrapper({
   // ...
});

// Navigate to an icon set
wrapper.setRoute({
   type: 'collection',
   params: {
       prefix: 'mdi',
   },
   parent: {
       type: 'collections',
   },
});

You can retrieve current route as part of state using getState().

selectIcons

This function changes currently selected icon(s).

Value must be an array of icons as Icon or string.

const wrapper = new Wrapper({
   // ...
});

// Select "mdi:home"
wrapper.selectIcons(['mdi:home']);

This function will trigger callback, so make sure you are not calling it in response to "selection" event or you might trigger an infinite loop.

If you try to select multiple icons, but option to select multiple icons is not enabled, only last icon will be selected.

You can retrieve currently selected icon(s) as part of state using getState().

setCustomisations

This function changes current icon customisations, such as color, dimensions, transformations.

const wrapper = new Wrapper({
   // ...
});

// Rotate currently selected icon by 90 degrees
wrapper.setCustomisations({
   rotate: 1,
});

You can retrieve list of active icon customisations as part of state using getState().