font_awesome_rails

Introduction

font_awesome_rails brings the fantastic Font Awesome iconic font to the Rails asset pipeline, with a bunch of new Sass styles for semantic markup.

Wouldn't be great if instead of

<a class="btn" href="..."><i class="icon-pencil"></i> Edit</a>

you could just write

<a class="edit btn" href="...">Edit</a>

so that down the line you can restyle your edit links with impunity (and save yourself some keystrokes while you're at it)?

Thanks to the mixins provided by font_awesome_rails, you can!

.edit.btn {
  @include icon(pencil);
}

Adding icons

icon-before($name)

mixin

Adds the named icon to the including element's ::before pseudoelement.

Example
wayfarers
HTML
<span class="icon-before">wayfarers</span>

SCSS
.icon-before {
  @include icon-before(glass);
}

icon-after($name)

mixin

Adds the named icon to the including element's ::after pseudoelement.

Example
mixtape
HTML
<span class="icon-after">mixtape</span>

SCSS
.icon-after {
  @include icon-after(cog);
}

icon($name)

mixin

Shorthand for icon-before.

Example
scenester
HTML
<span class="icon">scenester</span>

SCSS
.icon {
  @include icon(bolt);
}

icon($before, $after)

mixin

Adds the named icons to the including element's ::before and ::after pseudoelements.

Example
sriracha
HTML
<span class="icons">sriracha</span>

SCSS
.icons {
  @include icon(thumbs-up, thumbs-down);
}

Styling

One-off styles

All of the mixins that add icons can optionally take a content block with styles to be applied to the icon.

Example
thundercats
HTML
<span class="styled">thundercats</span>

SCSS
.styled {
  @include icon(facebook-sign) {
    color: #3B5998;
  }
}

icon-style

mixin

Applies styles (given in a content block) to all icons.

Example
polaroid gastropub
HTML
<span class="icon-before">polaroid</span>
<span class="icon-after">gastropub</span>

SCSS
span {
  @include icon-style {
    color: red;
  }
}

.icon-before {
  @include icon-before(flag);
}

.icon-after {
  @include icon-after(bullhorn);
}

icon-before-style

mixin

Applies styles (given in a content block) to all icons in ::before pseudoelements.

Example
quinoa fixie
HTML
<span class="icon-before">quinoa</span>
<span class="icon-after">fixie</span>

SCSS
span {
  @include icon-before-style {
    color: orange;
  }
}

.icon-before {
  @include icon-before(magic);
}

.icon-after {
  @include icon-after(pushpin);
}

icon-after-style

mixin

Applies styles (given in a content block) to all icons in ::after pseudoelements.

Example
vegan biodiesel
HTML
<span class="icon-before">vegan</span>
<span class="icon-after">biodiesel</span>

SCSS
span {
  @include icon-after-style {
    color: green;
  }
}

.icon-before {
  @include icon-before(headphones);
}

.icon-after {
  @include icon-after(leaf);
}

%icon-large

placeholder

Increases the icon size by one-third.

Example
cardigan
HTML
<span class="larger-icon">cardigan</span>

SCSS
.larger-icon {
  @extend %icon-large;
  @include icon(umbrella);
}

%icon-list

placeholder

Bullet lists with icons.

Example
  • organic
  • beard
  • leggings
HTML
<ul class="checklist">
  <li class="checked">organic</li>
  <li>beard</li>
  <li class="checked">leggings</li>
</ul>

SCSS
.checklist {
  @extend %icon-list;

  li {
    @include icon(check-empty);
  }

  li.checked {
    @include icon(check);
  }
}

Applications

The examples shown below are all based on those of Font Awesome itself (many of which are, in turn, based on those of Bootstrap). However, using font_awesome_rails eliminates a lot of the extraneous markup that was necessary in the original versions.

Buttons

HTML
<a class="refresh btn" href="#">Refresh</a>
<a class="cart btn" href="#">Checkout</a>
<a class="comment btn" href="#">Comment</a>
<a class="delete btn" href="#">Delete</a>
<a class="settings btn" href="#">Settings</a>
<a class="info btn" href="#">More Info</a>

SCSS
.refresh.btn {
  @include icon(refresh);
}

.cart.btn {
  @include icon(shopping-cart);
  @extend %icon-large;
  @extend .btn-success;
}

.comment.btn {
  @include icon(comment);
  @extend .btn-large;
  @extend .btn-primary;
}

.delete.btn {
  @include icon(trash);
  @extend %icon-large;
  @extend .btn-danger;
}

.settings.btn {
  @include icon(cog);
  @extend .btn-small;
}

.info.btn {
  @include icon(info-sign);
  @extend .btn-small;
  @extend .btn-info;
}

Button groups

Example
HTML
<div class="align toolbar">
  <button class="left" type="button"></button>
  <button class="center" type="button"></button>
  <button class="right" type="button"></button>
  <button class="justify" type="button"></button>
</div>

SCSS
.align.toolbar {
  @extend .btn-group;

  button {
    @extend .btn;
    @include icon-style {
      margin: 0;
    }
  }

  .left { @include icon(align-left); }
  .center { @include icon(align-center); }
  .right { @include icon(align-right); }
  .justify { @include icon(align-justify); }
}

Button dropdowns

HTML
<div class="user btn-group">
  <a class="btn" href="#">User</a>
  <a class="btn dropdown-toggle" data-toggle="dropdown" href="#"></a>
  <ul class="dropdown-menu">
    <li><a class="edit" href="#">Edit</a></li>
    <li><a class="delete" href="#">Delete</a></li>
    <li><a class="ban" href="#">Ban</a></li>
    <li class="divider"></li>
    <li><a class="admin" href="#">Make admin</a></li>
  </ul>
</div>

SCSS
.user.btn-group {
  .btn {
    @include icon(user);
    @extend .btn-primary;
  }

  .dropdown-toggle {
    @include icon(caret-down);
  }

  .edit { @include icon(pencil); }
  .delete { @include icon(trash); }
  .ban { @include icon(ban-circle); }
}

Prepended form inputs

Example
HTML
<form>
  <div class="email input">
    <span class="add-on"></span><input type="text" placeholder="Email address">
  </div>
  <div class="password input">
    <span class="add-on"></span><input type="password" placeholder="Password">
  </div>
</form>

SCSS
.input {
  @extend .input-prepend;

  .add-on {
    @include icon-style {
      margin: 0 0.25em;
    }
  }
}

.email .add-on {
  @include icon(envelope);
}

.password .add-on {
  @include icon(key);
}

Navigation

HTML
<nav class="sidebar">
  <ul>
    <li class="active"><a class="home" href="#">Home</a></li>
    <li><a class="library" href="#">Library</a></li>
    <li><a class="applications" href="#">Applications</a></li>
    <li><a class="settings" href="#">Settings</a></li>
  </ul>
</nav>

SCSS
nav.sidebar {
  @extend .well;
  padding: 8px 0;

  ul {
    @extend .nav;
    @extend .nav-list;
  }

  .home { @include icon(home); }
  .library { @include icon(book); }
  .applications { @include icon(pencil); }
  .settings { @include icon(cogs); }
}

Tabs

HTML
<nav class="tabs">
  <ul>
    <li class="active"><a class="home" href="#">Home</a></li>
    <li><a class="library" href="#">Library</a></li>
    <li><a class="applications" href="#">Applications</a></li>
    <li><a class="settings" href="#">Settings</a></li>
  </ul>
</nav>

SCSS
nav.tabs {
  ul {
    @extend .nav;
    @extend .nav-tabs;
  }

  .home { @include icon(home); }
  .library { @include icon(book); }
  .applications { @include icon(pencil); }
  .settings { @include icon(cogs); }
}

Images

font_awesome_rails can produce SVG images of the icon characters, which might be useful if you are trying to apply an icon to an element that doesn't have children (e.g. form inputs), or if you want to subset the font. Note that this is not supported in IE < 9.

Producing the SVG uses the nokogiri gem, so make sure you add it to your Gemfile before you try anything in this section.

icon-image($name)

mixin

Sets the background image to the named icon.

Example
mustache
HTML
<div class="speech">mustache</div>

SCSS
.speech {
  @include icon-image(comment-alt);
  background-size: 120px;
  width: 120px;
  height: 66px;
  padding-top: 30px;
  text-align: center;
}

icon-image($name, $style)

mixin

Sets the background image to the named icon with the specified style. $style is a list of SVG styling properties (notably fill changes the color) which are applied to the icon's path element.

Example
helvetica
HTML
<div class="heart">helvetica</div>

SCSS
.heart {
  @include icon-image(heart, "fill: red");
  color: white;
  background-size: 120px;
  width: 120px;
  height: 66px;
  padding-top: 30px;
  text-align: center;
}

About

font_awesome_rails