Skip to content
CLI gem for comfortably working with icon fonts (open, download, convert) from for usage in Rails apps.
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin Added --webpack option to "convert". Jan 27, 2017
lib bump version 0.4.6 Feb 1, 2017
spec Fix: webpack fails to generate embedded file. Jan 27, 2017
.gitignore convert code to gem with rake task Jun 19, 2013
.rspec basic specs Oct 7, 2013
.travis.yml added info to changelog Feb 1, 2017
Gemfile next try getting a recent version of bundler on travis Mar 28, 2016
LICENSE.txt convert code to gem with rake task Jun 19, 2013 Update README for Webpack. Feb 1, 2017
Rakefile add travis Dec 18, 2013
fontello_rails_converter.gemspec communicate that this gem depends on ruby 2.x Jun 9, 2015


Build Status

CLI gem for comfortably working with icon fonts from for usage in Rails apps.

Main features:

  • Open up your current fontello font in the browser from the command line
  • Copy & convert files from the zip into rails app (inclusively Sass enhancements)

Initial usage

Rails app setup

Add the gem to your Gemfile gem 'fontello_rails_converter' and run bundle install

Read the note below to decide whether to put the gem into the production or development group in your Gemfile.

Get your icon font

  1. Download your initial .zip file from and save it to myapp/tmp/

  2. Run bundle exec fontello convert --no-download inside your app's root directory

It will copy all the assets from the file into the appropiate places in your app's vendor/assets/ directory.

Use the font in your app

To use your font in your app you will need to @import the main stylesheet vendor/assets/stylesheets/fontname.css.scss in your application.css.sass using @import 'fontname'.

You can check if the icon font is working correctly by visiting http://localhost:3000/fontello-demo.html.

Updating your existing fontello font

When you want to add new icons to your existing fontello font you can open it in the browser by using fontello open and select all the additional icons you want to add.

Next you click the 'Save session' button on the fontello website. After that you can download, copy and convert the changed font by running bundle exec fontello convert (it has persisted the session id in tmp/fontello_session_id and will used that to pull down your changed font).

Alternatively, you can download & save the .zip file just like in the initial setp and run bundle exec fontello convert --no-download to use the manually downloaded file instead of pulling it down from fontello.


  • --webpack [command: convert]: generate the stylesheets for use with webpack, prefixing the font file names with the tilde (~). Es: src: url('~fontello.eot?99999999');. See Webpack.

More help

For more help run fontello --help

Sass enhacements

The conversion process will do a couple of things to make working with the main fontello stylesheet easier in Rails/Sass:

  • It will convert font paths to use font-url (unless you use the --webpack option)
  • It will create Sass placeholder selectors (e.g. %icon-foo for all the icons) so you have the choice to use the CSS classes in your markup or to @extend the placeholders in your Sass code


You can convert the fontello stylesheets for use with Webpack instead of Sprockets.

If you have not alreday done it, you must

  • add the vendor paths to the resolve roots of Webpack
const path = require("path")
const railsRoot = path.join(__dirname, ".")
module.exports = {
  resolve: {
    root: [
      path.join(railsRoot, './vendor/assets/javascripts'),
      path.join(railsRoot, './vendor/assets/stylesheets'),
      path.join(railsRoot, './vendor/assets/fonts'),
  • add optional parameters to the test key for the loader of the fonts files
test: /\.(png|woff|woff2|eot|ttf|svg)(\?[a-z0-9=.]+)?$/,


Additional fontello stylesheets

Besides the main stylesheet (fontname.css.scss) fontello also provides a couple of additional stylesheets that you might want to @import in your app for special use cases: fontname-ie7-codes.css.scss, fontname-embedded.css.scss, animation.css.scss, fontname-ie7.css.scss, fontname-codes.css.scss

Gemfile environment

If you don't want to load this gem in your app's production environment to save a tiny bit of memory, you can also just add it to the :development group in your Gemfile. The only thing you might need to change is to tell rails to add vendor/assets/fonts to the precompile load paths see:

Configuration file

By default the gem will look in Rails.root.join("config", "fontello_rails_converter.yml") for configuration options. You can use this to set default options for the tool.

You can’t perform that action at this time.