Custom fonts

Use the purgetss/fonts/ folder and the build-fonts command to register any font in your Titanium app: brand typefaces, custom icon fonts, or community icon libraries that PurgeTSS no longer bundles. The command detects Alloy and Classic projects automatically.

Output	Alloy	Classic
Font files	app/assets/fonts/	Resources/fonts/
Generated TSS classes	purgetss/styles/fonts.tss	Not generated
--module output	app/lib/purgetss.fonts.js	Resources/lib/purgetss.fonts.js

Classic projects receive only native Titanium resources and, when requested, a CommonJS module. They do not receive TSS files, app/, or an Alloy build hook.

The fonts folder

Place .ttf or .otf files in ./purgetss/fonts/. For icon fonts, also include the .css file that ships with the library. PurgeTSS reads it to extract the Unicode characters for each icon class.

This example uses Bevan and Dancing Script from Google Fonts:

./purgetss/fonts/

purgetss
└─ fonts
   ├─ Bevan-Italic.ttf
   ├─ Bevan-Regular.ttf
   ├─ DancingScript-Bold.ttf
   ├─ DancingScript-Medium.ttf
   ├─ DancingScript-Regular.ttf
   └─ DancingScript-SemiBold.ttf

Organizing the fonts folder

If you prefer to keep things tidy, group each family in a subfolder. The output is the same.

./purgetss/fonts/

purgetss
└─ fonts
   └─ bevan
      ├─ Bevan-Italic.ttf
      └─ Bevan-Regular.ttf
   └─ dancing-script
      ├─ DancingScript-Bold.ttf
      ├─ DancingScript-Medium.ttf
      ├─ DancingScript-Regular.ttf
      └─ DancingScript-SemiBold.ttf

The build-fonts command

$ purgetss build-fonts [-m] [-f]

# alias:
$ purgetss bf [-m] [-f]

In an Alloy project it:

1. Creates ./purgetss/styles/fonts.tss with one fontFamily class per file.
2. Copies the font files into ./app/assets/fonts/, renamed to their PostScript names so they work on both iOS and Android.

In a Classic project it copies the renamed files into ./Resources/fonts/. It deliberately skips fonts.tss and utility-class definitions because those belong to the Alloy/PurgeTSS styling workflow.

How this differs from the official icon fonts

In Alloy, unlike the official icon fonts, custom fonts generate ./purgetss/styles/fonts.tss. That file is folded into the generated app/styles/app.tss when you run purgetss (or compile your app). Classic projects skip this step and use the font's PostScript name directly through Titanium's fontFamily property.

After running purgetss build-fonts with the Bevan and Dancing Script example above:

./purgetss/styles/fonts.tss

// Fonts TSS file generated with PurgeTSS
// https://purgetss.com/docs/customization/custom-fonts

'.bevan-italic': { font: { fontFamily: 'Bevan-Italic' } }
'.bevan-regular': { font: { fontFamily: 'Bevan-Regular' } }

'.dancingscript-bold': { font: { fontFamily: 'DancingScript-Bold' } }
'.dancingscript-medium': { font: { fontFamily: 'DancingScript-Medium' } }
'.dancingscript-regular': { font: { fontFamily: 'DancingScript-Regular' } }
'.dancingscript-semibold': { font: { fontFamily: 'DancingScript-SemiBold' } }

In Alloy, you can now use these classes on any Titanium component with a font property: Labels, Buttons, TextFields, TextAreas, ListItems, TableViewRows, and ActivityIndicators.

In Classic, use the same PostScript name directly:

Resources/app.js

const label = Ti.UI.createLabel({
  text: 'Custom font',
  font: { fontFamily: 'DancingScript-Regular', fontSize: 24 }
})

Renaming the class

By default the class name comes from the font's PostScript name, so renaming the file changes nothing. To name the class after the file, rename it and run build-fonts with --font-class-from-filename (-f). For example:

./purgetss/fonts/

purgetss
└─ fonts
   └─ dancing-script
      ├─ Script-Bold.ttf
      ├─ Script-Medium.ttf
      ├─ Script-Regular.ttf
      └─ Script-SemiBold.ttf

Running purgetss build-fonts -f produces:

./purgetss/styles/fonts.tss

'.script-bold': { font: { fontFamily: 'DancingScript-Bold' } }
'.script-medium': { font: { fontFamily: 'DancingScript-Medium' } }
'.script-regular': { font: { fontFamily: 'DancingScript-Regular' } }
'.script-semibold': { font: { fontFamily: 'DancingScript-SemiBold' } }

The class name changes, but the actual fontFamily value (the PostScript name) stays the same.

Adding icon fonts

Any icon font that ships a .ttf (or .otf) plus a .css file with Unicode characters works the same way.

This example uses map-icons and microns:

./purgetss/fonts/

purgetss
└─ fonts
   └─ bevan
   └─ dancing-script
   └─ map-icons
      ├─ map-icons.css
      └─ map-icons.ttf
   └─ microns
      ├─ microns.css
      └─ microns.ttf

After purgetss build-fonts, the generated fonts.tss includes the family classes and one class per icon:

./purgetss/styles/fonts.tss

// Fonts TSS file generated with PurgeTSS
// https://purgetss.com/docs/customization/custom-fonts

'.map-icons': { font: { fontFamily: 'map-icons' } }
'.microns': { font: { fontFamily: 'microns' } }

/* Unicode Characters */
/* To use your Icon Fonts in Buttons AND Labels each class sets 'text' and 'title' properties */

/* map-icons/map-icons.css */
'.map-icon-abseiling': { text: '\ue800', title: '\ue800' }
'.map-icon-accounting': { text: '\ue801', title: '\ue801' }
'.map-icon-airport': { text: '\ue802', title: '\ue802' }
'.map-icon-amusement-park': { text: '\ue803', title: '\ue803' }
'.map-icon-aquarium': { text: '\ue804', title: '\ue804' }
/* ... */

/* microns/microns.css */
'.mu-arrow-left': { text: '\ue700', title: '\ue700' }
'.mu-arrow-right': { text: '\ue701', title: '\ue701' }
'.mu-arrow-up': { text: '\ue702', title: '\ue702' }
'.mu-arrow-down': { text: '\ue703', title: '\ue703' }
'.mu-left': { text: '\ue704', title: '\ue704' }
/* ... */

CSS formats and selector priority

PurgeTSS 7.20.1 reads literal glyphs from modern --fa declarations, as used by Font Awesome 7, and legacy content declarations. The glyph declaration can appear after other properties. Selector aliases receive their own classes, and supplementary Unicode is preserved in both TSS and CommonJS modules. A rule such as content: var(--fa) is a reference to another declaration and does not generate a glyph by itself.

In Alloy, each icon selector is resolved in this order:

1. purgetss/styles/fonts.tss generated by build-fonts.
2. purgetss/styles/fontawesome.tss for project Font Awesome Pro/Beta classes.
3. The bundled Font Awesome, Material Icons, Material Symbols and Framework7 catalogs.

A missing selector falls through to the next source. A selector defined in a higher-priority source is emitted once, using that definition. This applies to direct XML/controller classes and icon lookups in apply, including platform-specific target classes. A comment mentioning Font Awesome no longer suppresses its entire catalog.

Font-family classes and glyph classes remain separate: combine a custom glyph with the corresponding generated family class. build-fonts uses the font's PostScript name for its family class unless you select --font-class-from-filename; importing Pro CSS does not by itself create a fas family alias. The CSS parsing improvements also apply to generated Classic modules.

Options

Two optional flags adjust what build-fonts generates:

• -m, --module: generates a CommonJS module in ./app/lib/purgetss.fonts.js on Alloy or ./Resources/lib/purgetss.fonts.js on Classic. Its families object exposes the PostScript name of every processed TTF/OTF; when icon CSS is present, icons also exposes the Unicode map.
• -f, --font-class-from-filename: uses the font's filename as the font class name and icon prefix instead of the font family name. Useful when you want shorter prefixes. Replaces the old -p flag.

Using --module

$ purgetss build-fonts --module

# alias:
$ purgetss bf -m

The module is generated even when the source contains only ordinary text fonts. Every TTF/OTF contributes a key to families, so application code never needs to repeat or rediscover its embedded PostScript name. When CSS icon maps are present, each icon library also keeps its prefix as a nested object:

app/lib/purgetss.fonts.js (Alloy) or Resources/lib/purgetss.fonts.js (Classic)

const icons = {
  // map-icons/map-icons.css
  'mapIcon': {
    'abseiling': '\ue800',
    'accounting': '\ue801',
    'airport': '\ue802',
    'amusementPark': '\ue803',
    // ...
  },
  // microns/microns.css
  'mu': {
    'arrowLeft': '\ue700',
    'arrowRight': '\ue701',
    'arrowUp': '\ue702',
    'arrowDown': '\ue703',
    // ...
  }
};
exports.icons = icons;

const families = {
  'bevanItalic': 'Bevan-Italic',
  'bevanRegular': 'Bevan-Regular',
  'dancingScriptBold': 'DancingScript-Bold',
  'dancingScriptMedium': 'DancingScript-Medium',
  'dancingScriptRegular': 'DancingScript-Regular',
  'dancingScriptSemiBold': 'DancingScript-SemiBold',
  // map-icons/map-icons.css
  'mapIcon': 'map-icons',
  // microns/microns.css
  'mu': 'microns'
};
exports.families = families;

In a Classic app, the generated file lives at Resources/lib/purgetss.fonts.js. Titanium resolves local CommonJS paths from Resources/, so omit Resources/ and .js when loading it:

Resources/app.js

const customFonts = require('lib/purgetss.fonts')

const heading = Ti.UI.createLabel({
  text: 'Custom typography',
  font: {
    fontFamily: customFonts.families.dancingScriptSemiBold,
    fontSize: 28
  }
})

const airport = Ti.UI.createLabel({
  text: customFonts.icons.mapIcon.airport,
  font: {
    fontFamily: customFonts.families.mapIcon,
    fontSize: 24
  }
})

This follows Titanium's official CommonJS module path resolution.

Using --font-class-from-filename

When you want the class name and the icon prefix to come from the filename of the .ttf and .css instead of the font family, use -f.

./purgetss/fonts/

purgetss
└─ fonts
   └─ map-icons
      ├─ map.ttf
      └─ mp.css
   └─ microns
      ├─ mic.ttf
      └─ mc.css

./purgetss/styles/fonts.tss

/* "fontFamily" classes use the font's filename */
'.map': { font: { fontFamily: 'map-icons' } }
'.mic': { font: { fontFamily: 'microns' } }

/* map-icons/mp.css */
'.mp-abseiling': { text: '\ue800', title: '\ue800' }
'.mp-accounting': { text: '\ue801', title: '\ue801' }
'.mp-airport': { text: '\ue802', title: '\ue802' }
'.mp-amusement-park': { text: '\ue803', title: '\ue803' }
'.mp-aquarium': { text: '\ue804', title: '\ue804' }
/* ... */

/* microns/mc.css */
'.mc-arrow-left': { text: '\ue700', title: '\ue700' }
'.mc-arrow-right': { text: '\ue701', title: '\ue701' }
'.mc-arrow-up': { text: '\ue702', title: '\ue702' }
'.mc-arrow-down': { text: '\ue703', title: '\ue703' }
'.mc-left': { text: '\ue704', title: '\ue704' }
/* ... */

app/lib/purgetss.fonts.js (Alloy) or Resources/lib/purgetss.fonts.js (Classic)

const icons = {
  // map-icons/mp.css
  'mp': {
    'abseiling': '\ue800',
    'accounting': '\ue801',
    'airport': '\ue802',
    'amusementPark': '\ue803',
    // ...
  },
  // microns/mc.css
  'mc': {
    'arrowLeft': '\ue700',
    'arrowRight': '\ue701',
    'arrowUp': '\ue702',
    'arrowDown': '\ue703',
    // ...
  }
};
exports.icons = icons;

const families = {
  // map-icons/mp.css
  'mp': 'map-icons',
  // microns/mc.css
  'mc': 'microns'
};
exports.families = families;

Warning

Make sure the new prefix is unique and does not conflict with other class prefixes.

Custom proprietary icon fonts

If your design system ships its own icon font, treat it like any other icon library: drop the .ttf + .css pair into ./purgetss/fonts/<name>/ and run build-fonts. Alloy receives TSS classes. Classic can use the generated CommonJS module (--module) together with the exported font family, without adopting PurgeTSS utility classes.