font_awesomex

A library to render Font Awesome markup. Integrates seamlessly with your Phoenix application.

⚠️ This repository does not contain any Font Awesome assets. ⚠️

Prerequisites

• Elixir (>= 1.3)
• Font Awesome 4 (use your favorite package manager like NPM)

Installation

Add font_awesomex to your list of dependencies in mix.exs:

def deps do
  [{:font_awesomex, "~> 4.0.0"}]
end

Usage

Plain Ol' Elixir

iex> icon = FontAwesome.icon(:stop_circle, outline: true, size: 3)
%FontAwesome.Icon{name: "stop-circle", outline: true, size: 3, ...}

iex> to_string(icon)
"<i class=\"fa fa-stop-circle-o fa-size-3x\"></i>"

Following options are available:

Name	Description	Values	CSS Classes
:outline	Renders the outline variant (only some icons)	true, false	name suffixed with -o
:direction	Defines the direction (only some icons)	:left, :right, :up, :down	name suffixed with -left, -right, ...
:fixed_width	Fixes the icon width (may be configured globally)	true, false	fa-fw
:size	Scales the icon	:lg, 2, 3, 4	fa-lg, fa-2x
:rotate	Rotates the icon	0, 90, 180, 270	fa-rotate-90
:flip	Flips the icon horizontally or vertically	:horizontal, :vertical	fa-flip-vertical
:animate	Adds an animation to the icon	:spin, :pulse	fa-spin, fa-pulse
:list	Treats the icon as list bullet	true, false	fa-li
:border	Adds a border to the icon	true, false	fa-border
:pull	Aligns the icon left or right	:left, :right	fa-pull-left
:stacked	Indicates whether the icon is used in a stack	true, false	fa-stack

Phoenix Framework

To integrate the icon helpers with Phoenix views and templates you simply need to use it on top of your file:

defmodule MyApp.PageView do
  use MyApp.Web, :view
  use FontAwesome

  def hello_world do
    content_tag :div do
      [
        icon(:smile, outline: true, animate: :spin, size: 3),
        "Hello World"
      ]
    end
  end
end

If you want to add the helper to all views and templates, you can use or import it in the view/0 function of your web/web.ex file:

defmodule MyProject.Web do
  def view do
    quote do
      # Provides the icon/1 and icon/2 functions to all views and templates
      use FontAwesome
    end
  end
end

There may be cases when the default name (icon) conflicts with your existing implementation. In these cases you can define a name when using the module:

defmodule MyApp.PageView do
  use MyApp.Web, :view
  use FontAwesome, as: :fa_icon

  def scroll_down do
    [
      fa_icon(:arrow, direction: :down),
      "Scroll Down"
    ]
  end
end

Global Configuration

Alternatively, the helper name may be defined globally right from the start. So everytime you use FontAwesome, it generates a helper with the name you defined. Add this line to your config/config.exs:

config :font_awesomex, helper_name: :fa_icon

To make all icons have a fixed width by default, add the following line.

config :font_awesomex, fixed_width: true

The value can still be overridden per-icon.

What's missing

• Support for icon stacking

Contribution

• Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
• Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
• Fork the project.
• Start a feature/bugfix branch.
• Commit and push until you are happy with your contribution. Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.