Quasar Material Symbols: Setup and Usage
Quasar Material Symbols support takes three steps: load the font from @quasar/extras, optionally make it the icon set Quasar's own components use, and write icon names with the sym_o_, sym_r_ or sym_s_ prefix. This post walks through each step for Quasar CLI, the Quasar Vite plugin and Nuxt, then covers the three styles, the fill and weight axes, and the SVG version for smaller bundles. Everything matches Quasar 2.35.2 and @quasar/extras 2.1.0.
Material Symbols vs Material Icons
Material Icons is the set Quasar uses by default. Material Symbols is Google's newer set, and it differs in three ways that matter in a Quasar app:
- More icons. In
@quasar/extras2.1.0, each Material Symbols style has 3,912 icons, against 2,122 for each Material Icons style. More than 2,000 Material Symbols names have no Material Icons version. - Three styles instead of four. Outlined, Rounded and Sharp. There is no separate filled font. Fill is a setting instead (more on that below).
- Variable font axes. Fill, weight, grade and optical size can be changed with CSS on the webfont, per icon.
Most names are shared, so home, settings and delete exist in both. Switching sets mostly means changing the prefix.
Install @quasar/extras
The fonts ship in @quasar/extras. A Quasar CLI project usually has it already. Otherwise:
pnpm add @quasar/extrasThere is nothing to import by hand in Quasar CLI or Nuxt. You list the font by name in the config, and the build adds the CSS and the font file.
Enable Material Symbols in Quasar CLI
In quasar.config, extras loads the font and framework.iconSet tells Quasar's components to use it:
// quasar.config.js
export default defineConfig(() => ({
extras: ['material-symbols-outlined'],
framework: {
iconSet: 'material-symbols-outlined',
},
}))The two settings are separate on purpose. extras is what you can write in templates. iconSet is what Quasar's components draw: the QSelect dropdown arrow, the QChip remove icon, the QTable pagination chevrons. With only extras, your icons are Material Symbols and Quasar's built-in icons stay Material Icons, which then needs the material-icons font too. Setting both keeps the app on one font.
The valid names are material-symbols-outlined, material-symbols-rounded and material-symbols-sharp, for both extras and iconSet.
The Quasar Vite plugin way
With @quasar/vite-plugin and no Quasar CLI, import the font's CSS and the icon set in main.ts, next to the Quasar imports you already have:
// src/main.ts
import { createApp } from 'vue'
import { Quasar } from 'quasar'
import iconSet from 'quasar/icon-set/material-symbols-outlined'
import '@quasar/extras/material-symbols-outlined/material-symbols-outlined.css'
// ...your existing Quasar CSS import
import App from './App.vue'
createApp(App)
.use(Quasar, { iconSet })
.mount('#app')Enable Material Symbols in Nuxt
With the nuxt-quasar-ui module, set iconSet in the quasar key. When the icon set is a webfont, the module adds its font to extras.fontIcons for you (the autoIncludeIconSet option, on by default):
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['nuxt-quasar-ui'],
quasar: {
iconSet: 'material-symbols-outlined',
extras: {
fontIcons: ['material-symbols-rounded'],
},
},
})Here the outlined font comes in through iconSet, and fontIcons adds the rounded one for a few icons in your own templates. Leave fontIcons out if you only use one style. The Nuxt + Quasar setup guide covers the rest of the module's config.
Using outlined, rounded and sharp
Each style has its own prefix:
<template>
<div class="row q-gutter-md items-center">
<q-icon name="sym_o_home" size="md" />
<q-icon name="sym_r_home" size="md" />
<q-icon name="sym_s_home" size="md" />
</div>
</template>Names are snake_case, the same as on Google's icon site: account_circle, calendar_month, shopping_cart. Add the prefix and you have the Quasar name: sym_o_calendar_month.
Every style is a separate font file, and each one you use must be loaded. If sym_r_home shows as the plain word "home", the rounded font isn't in your config. Most apps pick one style and stay with it. Mixing styles costs an extra font download for little visual gain.
Icon props on other components take the same names:
<q-btn color="primary" icon="sym_o_add" label="New project" no-caps unelevated />
<q-input v-model="search" label="Search" clearable>
<template #prepend>
<q-icon name="sym_o_search" />
</template>
</q-input>size takes a CSS size or one of xs, sm, md, lg, xl, and color takes a Quasar palette name. Without them, the icon follows the surrounding text's size and color.
Fill, weight, grade and optical size
The Material Symbols fonts in @quasar/extras are variable fonts with four axes: FILL (0 to 1), wght (weight), GRAD (grade) and opsz (optical size). Set them with font-variation-settings. For one icon:
<q-icon
name="sym_o_favorite"
style="font-variation-settings: 'FILL' 1, 'wght' 400, 'GRAD' 0, 'opsz' 24"
/>For an app, put the axes behind CSS custom properties, scoped to the three Material Symbols classes, so a class or a style can change one axis without repeating the rest:
.q-icon.material-symbols-outlined,
.q-icon.material-symbols-rounded,
.q-icon.material-symbols-sharp {
font-variation-settings:
'FILL' var(--symbol-fill, 0),
'wght' var(--symbol-weight, 400),
'GRAD' var(--symbol-grade, 0),
'opsz' var(--symbol-optical-size, 24);
}
.q-icon.symbol-filled {
--symbol-fill: 1;
}<q-icon name="sym_o_star" />
<q-icon name="sym_o_star" class="symbol-filled" color="amber" />This is the usual way to show state: an outlined star for "not saved", a filled one for "saved". Only the class changes, and the icon name stays the same.
Weight is worth matching to your text: a lighter weight (300) sits better next to a thin UI font, a heavier one (500 or 600) next to bold headings.
The SVG version
Every Material Symbols icon also ships as an SVG export. Its name is the snake_case name in camelCase with a style prefix (symOutlined, symRounded, symSharp), and each style has its own module:
<script setup lang="ts">
import { symOutlinedHome } from '@quasar/extras/material-symbols-outlined'
import { symRoundedSettings } from '@quasar/extras/material-symbols-rounded'
</script>
<template>
<q-icon :name="symOutlinedHome" size="md" />
<q-btn flat round :icon="symRoundedSettings" aria-label="Settings" />
</template>Only the icons you import end up in the build, and there's no font to download first. Pair it with iconSet: 'svg-material-symbols-outlined' and you can drop the webfont. In Nuxt, extras.svgIcons: ['material-symbols-outlined'] makes the exports auto-imported, so the import lines go away.
The trade-off: SVG icons are fixed paths, so the fill and weight axes above don't apply. Pick the webfont if you need them, or if icon names come from data at runtime, since you can't import a name you only know later.
Common questions about Quasar Material Symbols
Why does my icon show as text? The font for that style isn't loaded, or the prefix is wrong. sym_o_ needs material-symbols-outlined, sym_r_ needs material-symbols-rounded, sym_s_ needs material-symbols-sharp.
Can I use Material Symbols and Material Icons together? Yes. Load both fonts. Unprefixed names (home) are Material Icons, and sym_ names are Material Symbols.
Where is the filled style? There is no filled font. Set 'FILL' 1 with font-variation-settings on the webfont.
Does Google Translate break the icons? Quasar adds the notranslate class to ligature icons, so translation tools leave the icon text alone.
Next step
Need a name? Quasar Icon Search searches Material Symbols and every other set Quasar supports, and gives you the sym_o_ name ready to paste, along with the extras or iconSet line for your config.