Custom icon packs

Icon packs are defined by XML resources. There's a XML file for the icons and a XML file for tags in each language.

Icons

Let's create a shapes icon pack. Icons XML has the following structure:

icons.xml

<icons width="24" height="24">
    <category id="0" name="@string/catg_shapes">
        <icon id="0" tags="shape,circle" path="M12 2A10 10 0 0 0 2 12A10 10 0 0 0 12 22A10 10 0 0 0 22 12A10 10 0 0 0 12 2Z"/>
        <icon id="1" tags="shape,triangle,three" path="M1 21H23L12 2"/>
        <icon id="2" tags="shape,square,four" path="M3 3V21H21V3"/>
        <icon id="3" tags="shape,pentagon,five" path="M12 2.5L2 9.8L5.8 21.5H18.2L22 9.8L12 2.5Z"/>
        <icon id="4" tags="shape,octagon,eight" path="M15.73 3H8.27L3 8.27V15.73L8.27 21H15.73L21 15.73V8.27"/>
    </category>
    <category id="1" name="@string/catg_stars">
        <icon id="5" tags="shape,star,three" path="M12 2.6L9 12.4L2 19.9L12 17.6L22 20L15 12.5L12 2.6Z"/>
        <icon id="6" tags="shape,star,four" path="M12 1L9 9L1 12L9 15L12 23L15 15L23 12L15 9L12 1Z"/>
        <icon id="7" tags="shape,star,five" path="M12 17.27L18.18 21L16.54 13.97L22 9.24L14.81 8.62L12 2L9.19 8.62L2 9.24L7.45 13.97L5.82 21L12 17.27Z"/>
        <icon id="8" tags="shape,star,eight" path="M2.2 16.06L3.88 12L2.2 7.94L6.26 6.26L7.94 2.2L12 3.88L16.06 2.2L17.74 6.26L21.8 7.94L20.12 12L21.8 16.06L17.74 17.74L16.06 21.8L12 20.12L7.94 21.8L6.26 17.74L2.2 16.06Z"/>
    </category>
</icons>

The icon pack defines a global viewport width and height that applies to all icons. In addition icons can have the following attributes:

• id: required, uniquely identifies the icon. Must be non-negative.
• tags: optional, the list of tags separated by a comma.
• path/src: Icon data, either as SVG path data, or from a XML drawable (e.g.: src="@drawable/ic_plus")
• width: icon viewport width, overrides global width.
• height: icon viewport height, overrides global height.
• category: if icon isn't wrapped in a <category> element, specifies the icon's category.

Tags

The tags referenced in the tags attributes in the icons XML are defined in a separate file.

tags.xml

<tags>
    <tag name="shape">Shape</tag>
    <tag name="star">Star</tag>
    <tag name="circle">Circle</tag>
    <tag name="triangle">Triangle</tag>
    <tag name="square">
        <alias>Square</alias>
        <alias>Rectangle</alias>
    </tag>
    <tag name="pentagon">Pentagon</tag>
    <tag name="octagon">Octagon</tag>
    <tag name="three">Three</tag>
    <tag name="four">Four</tag>
    <tag name="five">Five</tag>
    <tag name="eight">
        <alias>8</alias>
        <alias>Eight</alias>
    </tag>
</tags>

As you can see, tags can have a single value, or multiple values, defined with <alias> tags. This allows you to define synonyms to make search more reliable.

Loading the icon pack

The icon pack is loaded with the IconPackLoader class using the XML files and a list of supported locales.

Kotlin

val loader = IconPackLoader(context)
val iconPack = loader.load(R.xml.icons, R.xml.tags, listOf(Locale.ENGLISH))

Java

IconPackLoader loader = new IconPackLoader(this);
IconPack iconPack = loader.load(R.xml.icons, R.xml.tags, Collections.singletonList(Locale.ENGLISH), null);

You can also specify a parent pack to add or overwrite icons to an existing pack:

val parentPack = createDefaultIconPack(loader)
val iconPack = loader.load(R.xml.icons, R.xml.tags, listOf(Locale.ENGLISH), parentPack)

Note that in this case, icons will be overwritten and not added since the IDs we used are already being used by the parent pack. The existing categories names will also be overriden. When overwriting an existing category or icon, omitted attributes will be resolved from the parent pack. This way, it is possible for example to change an icon's tags without redefining its path.