Adding New Icons

A practical checklist for what to actually do — and what you can safely skip — when a new icon is added to any mapping.json.

What’s required vs. optional

Full worked examples, A to Z

The table above tells you what’s required. These three walk through doing it for real, one per library — every command, every file touched, nothing skipped:

• Example: Adding an Icon to glyphicons-v2
• Example: Adding an Icon to glyphicons-v1
• Example: Adding an Icon to phpc

Adding a whole new icon set

For a brand-new sub-folder (e.g. adding filetypes to glyphicons-v1) or a whole new top-level library — the folder and its mapping.json don’t exist yet.

How much work depends on two things

IconDropdown.tsx: one import per sub-folder, or one combined file?

glyphicons-v1 imports each sub-folder’s mapping.json by name — one import per sub-folder, forever:

import iconsGlyphiconsV1Basic from "../../icons/glyphicons-v1/basic/mapping.json";
import iconsGlyphiconsV1Filetypes from "../../icons/glyphicons-v1/filetypes/mapping.json";

glyphicons-v2 and phpc each import one file instead, rebuilt by script/generate-mapping.py (step 3 below):

import iconsGlyphiconsV2 from "../../icons/glyphicons-v2/mapping-with-filepath.json";
import iconsPHPC from "../../icons/phpc/mapping-with-filepath.json";

Real constraint, not a style choice: a JS import path has to be written by a person ahead of time — a script that walks the filesystem doesn’t.

generate-keywords.py: hand-written list, or auto-discovered?

Both scripts build a sets list of (mapping.json, ..., keywords.json, ...) entries. glyphicons-v2’s are hand-written, one tuple per sub-folder:

("icons/glyphicons-v2/basic/mapping.json", "", "icons/glyphicons-v2/basic/keywords.json", "-"),
("icons/glyphicons-v2/halflings/mapping.json", "", "icons/glyphicons-v2/halflings/keywords.json", "-"),

phpc’s are discovered instead, with no folder name written anywhere:

for mapping_path in sorted(glob.glob("icons/phpc/**/mapping.json", recursive=True)):
    out_path = mapping_path.replace("mapping.json", "keywords.json")
    sets.append((mapping_path, "", out_path, "-"))

1. Create the folder

icons/<library>/<subfolder>/, containing the .svg files plus one mapping.json:

icons/
├─ glyphicons-v1/{basic,halflings,filetypes,socials}/
├─ glyphicons-v2/{basic,halflings,filetypes}/   ← e.g. a new subfolder here
└─ phpc/

2. Normalize mapping.json

{
  "file-bookmark": "glyphicons-filetypes-89-file-bookmark.svg",
  "file-stats": "glyphicons-filetypes-31-file-stats.svg"
}

If your source data isn’t already in that shape

Raw exports sometimes reverse the key/value roles, or use ligature codes instead of filenames. jq reshapes it fast.

Example — value is a ligature code, not a filename:

{
  "glyphicons-txt": "E001",
  "glyphicons-doc": "E002"
}

jq 'map_values("icon_uni" + . + ".svg")' mapping.json > new_mapping.json

jq 'with_entries(.key |= sub("glyphicons-"; ""))' new_mapping.json > mapping.json

Result:

{
  "txt": "icon_uniE001.svg",
  "doc": "icon_uniE002.svg"
}

3. Get the icons into the dropdown

A. glyphicons-v2 or phpc — a new sub-folder under an existing library

Nothing to import by hand — both rebuild from one combined file:

cd icons/
python ../script/generate-mapping.py ./glyphicons-v2
# writes mapping-with-filepath.json — move it into glyphicons-v2/ if it isn't already there

IconDropdown.tsx already imports that file — a new sub-folder is picked up the next time this script runs, no code change:

import iconsGlyphiconsV2 from "../../icons/glyphicons-v2/mapping-with-filepath.json";

B. glyphicons-v1, font-awesome, or a genuinely new top-level library

Hardcoded in IconDropdown.tsx: every sub-folder gets its own import plus a manual lookup entry.

import iconsGlyphiconsV1Filetypes from "../../icons/glyphicons-v1/filetypes/mapping.json";
import iconsGlyphiconsV1FiletypesKeywords from "../../icons/glyphicons-v1/filetypes/keywords.json";

const v1Sets = {
  "glyphicons-v1/basic": iconsGlyphiconsV1Basic,
  "glyphicons-v1/filetypes": iconsGlyphiconsV1Filetypes, // new
  // ...other existing entries
};
const v1KeywordSets: Record<string, Record<string, string[]>> = {
  "glyphicons-v1/basic": iconsGlyphiconsV1BasicKeywords,
  "glyphicons-v1/filetypes": iconsGlyphiconsV1FiletypesKeywords, // new
  // ...other existing entries
};

Object.entries(v1Sets).forEach(([prefix, iconSet]) => {
  const keywordSet = v1KeywordSets[prefix];
  Object.entries(iconSet).forEach(([name, path]) => {
    iconsArray.push({
      value: `${prefix}/${name}`,
      label: name,
      iconUrl: `${baseUrl}${prefix}/${path}`,
      keywords: keywordSet?.[name],
    });
  });
});

Related pages

• Search in IconDropdown — how matchesSearch and the keywords field actually work
• Keywords & Translations — the source files behind that keyword search, and how they’re combined