IconTree Integration Docs

https://icontree.cosmoscope.workers.dev

Format Note

Do not write SVG-loading, SVG-parsing, or SVG-fallback code for these icons. There is no SVG available from this source — every icon, in both modes below, is a .json file passed to the platform’s Lottie player component.

How IconTree Works

Integration is a two-step flow: select at design time, then ship locally.

1. Search the library with /icon/search (you, the developer — not the running app).
2. Pick the icons you need from results[].
3. Download each icon’s JSON (fetch https://icontree.cosmoscope.workers.dev + result.url) and bundle it into your app.
4. Load the bundled JSON the idiomatic way for your stack and render it with a Lottie player.

React — icon-tree-animate (recommended)

If your project uses React 18+, install the official icon-tree-animate npm package. It handles icon discovery, local bundling, runtime color control, and 4 playback modes — no manual JSON management needed.

Install

npm install icon-tree-animate

Add icons (CLI)

Run this once per icon at design time. It searches IconTree, saves the JSON locally, and registers the icon.

npx icontree add heart --search "heart"
npx icontree add arrow-right --search "arrow right"
npx icontree add arrow-right --search "arrow right" --interactive  # pick from multiple results

Use the component

import { Icon } from "icon-tree-animate";

<Icon id="heart" size={48} color="#ff0000" mode="static" />
<Icon id="heart" size={48} color="#00ff00" mode="loop" />
<Icon id="heart" size={48} color="#0000ff" mode="onClick" onClick={() => handleClick()} />
<Icon id="heart" size={48} color="#ffaa00" mode="hover" />

Props

Modes

• static — Frame 0 only. No animation.
• loop — Autoplay, infinite.
• onClick — Idle at frame 0, plays once on click.
• hover — Idle at frame 0, plays once on mouse-enter, finishes on mouse-leave.

How it works

Design-time (CLI): add-icon.js fetches raw Lottie JSON from the IconTree API and saves it to src/icons/. No colors are applied.

Runtime (Component): The icon JSON is loaded via dynamic import (tree-shakeable), recolored in-memory using the color prop, and rendered via Lottie. Zero network requests. The recolorLottie() function deep-clones the JSON, converts hex to Lottie RGBA float format, walks the layer tree updating fill/stroke, and memoizes by icon + color.

The shipped app should never call /icon/search at runtime. Selection happens once, while you author the code; the final code is local and static.

Mode 2 — Manual / Local (recommended for shipped apps)

You do not have to call the API at runtime. Once you have selected and downloaded the JSON files (using the search endpoint at design time), keep them inside your app and load them locally.

Manual mode means:
1. Pick an icon on IconTree
2. Download or copy its .json file
3. Save it inside your app project
4. Load that local file with your platform's Lottie player

Use manual mode when you already know which icons you want and do not need runtime search.

// Put the file in:
// app/src/main/assets/lottie/arrow-right-bold.json

lottieView.setAnimation("lottie/arrow-right-bold.json")
lottieView.playAnimation()

import lottie from "lottie-web";
import animationData from "./lottie/arrow-right-bold.json";

lottie.loadAnimation({
  container: document.getElementById("icon"),
  renderer: "svg",
  loop: true,
  autoplay: true,
  animationData,
});

Search Response Shape

GET https://icontree.cosmoscope.workers.dev/icon/search?q=arrow&page=1&pageSize=20

{
  "query": "arrow",
  "category": "",
  "count": 12,
  "results": [
    {
      "name": "arrow-right-bold",
      "slug": "arrow-right-bold",
      "filename": "arrow-right-bold.json",
      "tags": ["arrow", "direction", "ui"],
      "category": "navigation",
      "size": 1583,
      "url": "/icon/use/arrow-right-bold.json"
    }
  ]
}

Endpoint Reference

Platform Guides

The snippets below show how to fetch an icon at design time (to download and bundle it). For the shipped app, load the bundled JSON locally and render it with your Lottie player — do not keep the fetch in production code.

// settings.gradle / build.gradle
// Add the current Lottie Android dependency for your project.
implementation("com.airbnb.android:lottie:<latest-version>")

suspend fun loadIconTreeAnimation(query: String): String? {
    val searchUrl = "https://icontree.cosmoscope.workers.dev/icon/search?q=$" + "{URLEncoder.encode(query, "UTF-8")}&page=1&pageSize=20"
    val searchText = URL(searchUrl).readText()
    val searchJson = JSONObject(searchText)
    val results = searchJson.getJSONArray("results")

    if (results.length() == 0) return null

    val first = results.getJSONObject(0)
    return "https://icontree.cosmoscope.workers.dev$" + "{first.getString("url")}"
}

// Then pass the returned URL to Lottie:
// lottieView.setAnimationFromUrl(iconUrl)

const search = await fetch(
  "https://icontree.cosmoscope.workers.dev/icon/search?q=arrow&page=1&pageSize=20"
).then((r) => r.json());

const firstIcon = search.results[0];
const animationData = await fetch("https://icontree.cosmoscope.workers.dev" + firstIcon.url).then((r) => r.json());

lottie.loadAnimation({
  container: document.getElementById("icon"),
  renderer: "svg",
  loop: true,
  autoplay: true,
  animationData,
});

import { useEffect, useRef } from "react";
import lottie from "lottie-web";

export function IconTreePreview({ slug }) {
  const containerRef = useRef(null);

  useEffect(() => {
    let animation;

    async function load() {
      const data = await fetch("https://icontree.cosmoscope.workers.dev/icon/use/" + slug + ".json").then((r) => r.json());

      animation = lottie.loadAnimation({
        container: containerRef.current,
        renderer: "svg",
        loop: true,
        autoplay: true,
        animationData: data,
      });
    }

    load();
    return () => animation?.destroy();
  }, [slug]);

  return <div ref={containerRef} style={{ width: 32, height: 32 }} />;
}

const response = await fetch(
  "https://icontree.cosmoscope.workers.dev/icon/search?q=mail&category=communication&page=1&pageSize=20"
);
const data = await response.json();

console.log(data.results.map((icon) => ({
  name: icon.name,
  jsonUrl: "https://icontree.cosmoscope.workers.dev" + icon.url,
})));

import requests

search = requests.get(
    "https://icontree.cosmoscope.workers.dev/icon/search",
    params={"q": "search", "page": 1, "pageSize": 20},
).json()

if search["results"]:
    first = search["results"][0]
    icon_json = requests.get("https://icontree.cosmoscope.workers.dev" + first["url"]).json()
    print(first["name"], icon_json["v"])

curl "https://icontree.cosmoscope.workers.dev/icon/search?q=arrow&page=1&pageSize=20"

Best Practices

• Use the search API to select icons at design time; ship them as local JSON (Mode 2).
• The running app should never call /icon/search — bundle the icons instead.
• IconTree is Lottie-JSON only: no SVG loading/parsing/fallback code.
• Recolor icons to your theme — the source JSON often ships a fixed fill (white/black) that won’t match light/dark.
• Use pageSize=20 when scrolling the search results during selection.
• Keep the original name and slug returned by the API.
• Cache fetched icon JSON where possible. Responses are immutable per build.
• If search returns no results, try a broader query or remove the category filter.

Icon Color & Recoloring

IconTree icons ship with a fixed fill color baked into the Lottie JSON (often white or black) that isnot guaranteed to match your app’s theme. Recolor the icon so it follows your app’s light/dark/custom theme instead of the source JSON’s color.

Recolor at download time (recommended)

The /icon/use endpoint accepts a color query parameter. It returns the same Lottie JSON with its fill/stroke (fl/st/gf) colors swapped to your hex value — no runtime color code needed in your app.

GET $https://icontree.cosmoscope.workers.dev/icon/use/arrow-right-bold.json?color=ff0000

# The leading # is optional — use just the code: color=ff0000 or color=%23ff0000 both work.
# Valid hex: RRGGBB or RRGGBBAA (with or without #)

Download that recolored JSON and bundle it locally (per the workflow above). For light/dark support, fetch and bundle two variants — e.g. ?color=%23222 for light and ?color=%23fff for dark.

Recolor at runtime (alternative)

If the app must recolor at runtime, use the idiomatic mechanism for your platform’s Lottie player — e.g. runtime color callbacks / dynamic properties, colorFilters, or a JSON preprocessing step that swaps fill/stroke color values before passing the data to the player.

Source & Repository

IconTree is open source. Grab the code, report issues, or contribute new icons on GitHub:

https://github.com/HasibulHasan098/IconTree

IconTree v1 · 946 icons available · GitHub