Drop Material Icons webfonts in favour of tree-shaken SVG icons
Goal: Ship the app with zero icon webfonts — every icon rendered as an inline SVG, tree-shaken so only the icons in use are bundled.
Architecture: Two icon surfaces both moved to SVG: (1) Quasar's internal component icons (dropdown arrows, sort carets, checkboxes, stepper, pagination, close buttons inside q-select/q-chip) — switched in one line via framework.iconSet: 'svg-material-icons'; (2) app-authored icons — every <q-icon name="…">, icon="…" prop, and config icon: '…' field — converted to in-component named imports from @quasar/extras/material-icons (mat*) and @quasar/extras/material-icons-outlined (outlined*). With extras: [], nothing resolves a ligature name any more.
Delivered (PR #1603)¶
Measured with quasar build, origin/dev (85ad0f71) vs. branch tip:
| before | after | delta | |
|---|---|---|---|
dist/spa total (raw) |
5139.2 KiB | 4543.8 KiB | −595.4 KiB |
icon webfont bytes in dist |
634.0 KiB | 0 | −634.0 KiB |
| …of which woff2 (what a browser fetches) | 277.2 KiB | 0 | −277.2 KiB |
| entry JS+CSS, gzipped | 240.0 KiB | 255.6 KiB | +15.6 KiB |
Net first-load transfer for a page that renders any icon: ≈ −261 KiB, and the two font-display: block icon fonts leave the LCP critical path. The +15.6 KiB is the inlined SVG path data for the ~120 icons in use, mostly in the eagerly-loaded navigation chunk.
Scope: 248 call sites across 86 files were still on ligature names at rebase time; all are converted. Roughly 40 % of the sweep came from the original 2026-06 commits (rebased onto dev), the rest from a single sweep over current dev.
Names Google dropped from the legacy set¶
Six names have no @quasar/extras SVG export. Five of them have no ligature in the shipped webfont either (verified against the font's GSUB table) — they were rendering as nothing in production, so the substitution fixes a latent bug rather than changing a working icon. Only o_eco was a real glyph before.
| name | substitute | in the old webfont? |
|---|---|---|
info_outline |
outlinedInfo |
no |
manufacturing |
matPrecisionManufacturing |
no |
o_check_small |
outlinedCheck |
no |
o_edit_document |
outlinedEditNote |
no |
o_table |
outlinedTableChart |
no |
o_eco |
outlinedEnergySavingsLeaf |
yes — genuine visual change |
o_eco's only call site is inside a <!-- TEMPORARILY HIDDEN --> block in WorkspaceSelectorBar.vue; commented-out markup was left as-is, so that substitute is not wired up yet.
Guard¶
frontend/tests/unit/svg-icons.spec.ts replaces the per-area grep guards and the dev-only iconMapFn boot file this plan originally called for. It asserts (a) no source file references an icon by ligature name, (b) quasar.config.js keeps extras: [] and the SVG icon set, (c) a converted component renders an inline <svg> and no .material-icons element. A runtime guard would add nothing: no icon name reaches q-icon from the backend or from i18n, so every call site is statically visible.
Constraints (still binding when adding icons)¶
- Do not touch
ModuleIcon/ModuleIconBox/module-iconplugin usages (:name="module",:name="row.module", …). Those render custom module SVGs (src/assets/icons/modules/*.svgviaimport.meta.globraw import) and are unrelated to the webfonts. - Do not convert i18n keys, domain strings, or any non-icon
name:/icon:property. Many snake_case strings (room_name,results_units_kg, …) are translation keys. - Verification:
cd frontend && make type-check(a non-existent export name fails to compile),make lint(catches a half-done conversion as an unused import), andnpm run test-ct.
Background — current state (measured 2026-06-18)¶
Lighthouse on …/2025/equipment:
flUhRq6tz…woff2— 126 KiB, Material Icons,font-display: block(FOIT), on LCP critical path (~1,020 ms).gok-H7zzD…woff2— 152 KiB, Material Icons Outlined,font-display: block, on LCP critical path (~1,249 ms).- Both injected unconditionally by the top-level
extras: ['material-icons', 'material-icons-outlined']inquasar.config.js— not by anything underframework.
Call-site inventory (frontend src/), re-measured against origin/dev on 2026-09-10:
120distinct icon names over248call sites in86files acrosscomponents/,pages/,constant/,api/(2026-06 figures were 111 / ~226 / ~80).:name="…"bindings that targetModuleIcon/ModuleIconBoxare out of scope (custom SVGs).
Conversion recipe — how to add an icon¶
For each affected file:
- Template literal → bound SVG import.
<!-- before --> <!-- after --> <q-icon name="close" /> <q-icon :name="matClose" /> <q-btn icon="o_info" /> <q-btn :icon="outlinedInfo" /> - Ternary literal → bound import (import both branches).
<!-- before --> <q-icon :name="collapsed ? 'chevron_right' : 'chevron_left'" /> <!-- after --> <q-icon :name="collapsed ? matChevronRight : matChevronLeft" /> - Config object field (
.ts/<script>).The consuming template (// before { label: 'Close', icon: 'o_close' } // after import { outlinedClose } from '@quasar/extras/material-icons-outlined' { label: 'Close', icon: outlinedClose }:icon="item.icon") stays unchanged — SVG exports are plainstrings ("path…|viewBox"), so existingicon: stringtypes still hold. - Add imports at the top of the file, grouped by source:
import { matClose, matRefresh } from "@quasar/extras/material-icons"; import { outlinedInfo, outlinedClose, } from "@quasar/extras/material-icons-outlined"; - Derive the export name with the naming rule below.
- Do not convert
ModuleIcon/ModuleIconBox/module-icon:namebindings, or non-icon properties.
After editing a file, the name=/icon=/icon: literal must be gone (it is now :name/:icon bound, or icon: <import>).
What NOT to touch (explicit allow-list of survivors)¶
<ModuleIcon :name="…">,<ModuleIconBox :name="…">,module-icon— custom module SVGs.:name="icon"whereiconis a prop/variable (e.g.EssentialLink.vue,VirtualSelectField.vue) — already dynamic; the source value gets converted at its origin (config / computed), not here.- Any
name:/icon:that is not an icon (i18n keys, type discriminators, API fields).
Naming rule¶
o_x_y → outlinedXY (from @quasar/extras/material-icons-outlined); every other name → matXY (from @quasar/extras/material-icons). A name that does not exist as an export fails make type-check, so there is nothing to memorise — the six names with no export at all are listed in the table above.
Follow-ups¶
- Re-run Lighthouse on
…/2025/equipmentto confirm the icon-font payload and its FOIT are gone from the LCP critical path. - Confirm the six substituted icons visually (table above); only
o_ecochanges a glyph that used to render, and its one call site is currently commented out. - Sixteen of the touched
.vuefiles were already over the 500-line component limit before this change; they each gain one import line and were deliberately not refactored here.